curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"template": {
"name": "order_shipped",
"category": "UTILITY",
"language": "en_US",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Your order is on its way"
},
{
"type": "BODY",
"text": "Hi {{1}}, order {{2}} has shipped.",
"example": {
"body_text": [
[
"Ana",
"10482"
]
]
}
},
{
"type": "FOOTER",
"text": "Reply STOP to opt out"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Track order"
}
]
}
]
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates"
payload = { "template": {
"name": "order_shipped",
"category": "UTILITY",
"language": "en_US",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Your order is on its way"
},
{
"type": "BODY",
"text": "Hi {{1}}, order {{2}} has shipped.",
"example": { "body_text": [["Ana", "10482"]] }
},
{
"type": "FOOTER",
"text": "Reply STOP to opt out"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Track order"
}
]
}
]
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
template: {
name: 'order_shipped',
category: 'UTILITY',
language: 'en_US',
components: [
{type: 'HEADER', format: 'TEXT', text: 'Your order is on its way'},
{
type: 'BODY',
text: 'Hi {{1}}, order {{2}} has shipped.',
example: {body_text: [['Ana', '10482']]}
},
{type: 'FOOTER', text: 'Reply STOP to opt out'},
{type: 'BUTTONS', buttons: [{type: 'QUICK_REPLY', text: 'Track order'}]}
]
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'template' => [
'name' => 'order_shipped',
'category' => 'UTILITY',
'language' => 'en_US',
'components' => [
[
'type' => 'HEADER',
'format' => 'TEXT',
'text' => 'Your order is on its way'
],
[
'type' => 'BODY',
'text' => 'Hi {{1}}, order {{2}} has shipped.',
'example' => [
'body_text' => [
[
'Ana',
'10482'
]
]
]
],
[
'type' => 'FOOTER',
'text' => 'Reply STOP to opt out'
],
[
'type' => 'BUTTONS',
'buttons' => [
[
'type' => 'QUICK_REPLY',
'text' => 'Track order'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates"
payload := strings.NewReader("{\n \"template\": {\n \"name\": \"order_shipped\",\n \"category\": \"UTILITY\",\n \"language\": \"en_US\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"format\": \"TEXT\",\n \"text\": \"Your order is on its way\"\n },\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, order {{2}} has shipped.\",\n \"example\": {\n \"body_text\": [\n [\n \"Ana\",\n \"10482\"\n ]\n ]\n }\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Reply STOP to opt out\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Track order\"\n }\n ]\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"template\": {\n \"name\": \"order_shipped\",\n \"category\": \"UTILITY\",\n \"language\": \"en_US\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"format\": \"TEXT\",\n \"text\": \"Your order is on its way\"\n },\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, order {{2}} has shipped.\",\n \"example\": {\n \"body_text\": [\n [\n \"Ana\",\n \"10482\"\n ]\n ]\n }\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Reply STOP to opt out\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Track order\"\n }\n ]\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"template\": {\n \"name\": \"order_shipped\",\n \"category\": \"UTILITY\",\n \"language\": \"en_US\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"format\": \"TEXT\",\n \"text\": \"Your order is on its way\"\n },\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, order {{2}} has shipped.\",\n \"example\": {\n \"body_text\": [\n [\n \"Ana\",\n \"10482\"\n ]\n ]\n }\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Reply STOP to opt out\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Track order\"\n }\n ]\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "1157693219400316",
"name": "order_shipped",
"language": "en_US",
"category": "UTILITY",
"status": "PENDING"
}{
"error": {
"code": "bad_request",
"message": "The request is malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "This account is suspended."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "template",
"code": "meta_rejected",
"message": "A template with this name already exists. Choose a different name."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}{
"error": {
"code": "service_unavailable",
"message": "WhatsApp did not answer in time. Check the template before retrying: it may already have been submitted."
}
}Create a message template
Submits a new message template to WhatsApp on a WhatsApp Cloud API inbox.
Meta reviews every template before it can be sent. The call answers 201 with the status Meta assigned, normally PENDING, not with a template you can use yet. Review takes from minutes to a day and this API does not report when it ends: List message templates returns approved templates only, so the template appears there once Meta approves it and your account’s catalogue syncs, a few minutes later. Do not use a template in a campaign before it shows up in that list.
Administrators only, and only on an official WhatsApp Cloud API inbox; any other inbox answers 422 with code unsupported_channel. Headers are text only (format TEXT) or left out; a media header answers 422 with code header_not_supported, and media headers are created in the Cloud Chat screen. Templates cannot be deleted through this API.
These rules are checked before Meta is called and answer 422 with code invalid_template and an explanation: the BODY uses either positional variables ({{1}}) or named ones ({{customer_name}}), never both, and a variable name is unaccented letters, digits and underscores; a template has at most 10 buttons, of which at most 2 are URL buttons, 1 a phone number and 1 a copy-code button; a copy-code button is only allowed on a MARKETING template and its example code is at most 15 characters; a URL button whose url carries a variable needs an example. An AUTHENTICATION template has no HEADER, a BODY without text (set add_security_recommendation), a FOOTER with code_expiration_minutes between 1 and 90, and exactly one OTP button with otp_type COPY_CODE and text of at most 25 characters. Give a sample for every BODY variable: Meta refuses variables without one.
Meta’s own refusals, such as a name already used in the same language, answer 422 with code meta_rejected and Meta’s explanation. Do not repeat the call after a 503: the template may already have been submitted.
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"template": {
"name": "order_shipped",
"category": "UTILITY",
"language": "en_US",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Your order is on its way"
},
{
"type": "BODY",
"text": "Hi {{1}}, order {{2}} has shipped.",
"example": {
"body_text": [
[
"Ana",
"10482"
]
]
}
},
{
"type": "FOOTER",
"text": "Reply STOP to opt out"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Track order"
}
]
}
]
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates"
payload = { "template": {
"name": "order_shipped",
"category": "UTILITY",
"language": "en_US",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Your order is on its way"
},
{
"type": "BODY",
"text": "Hi {{1}}, order {{2}} has shipped.",
"example": { "body_text": [["Ana", "10482"]] }
},
{
"type": "FOOTER",
"text": "Reply STOP to opt out"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Track order"
}
]
}
]
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
template: {
name: 'order_shipped',
category: 'UTILITY',
language: 'en_US',
components: [
{type: 'HEADER', format: 'TEXT', text: 'Your order is on its way'},
{
type: 'BODY',
text: 'Hi {{1}}, order {{2}} has shipped.',
example: {body_text: [['Ana', '10482']]}
},
{type: 'FOOTER', text: 'Reply STOP to opt out'},
{type: 'BUTTONS', buttons: [{type: 'QUICK_REPLY', text: 'Track order'}]}
]
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'template' => [
'name' => 'order_shipped',
'category' => 'UTILITY',
'language' => 'en_US',
'components' => [
[
'type' => 'HEADER',
'format' => 'TEXT',
'text' => 'Your order is on its way'
],
[
'type' => 'BODY',
'text' => 'Hi {{1}}, order {{2}} has shipped.',
'example' => [
'body_text' => [
[
'Ana',
'10482'
]
]
]
],
[
'type' => 'FOOTER',
'text' => 'Reply STOP to opt out'
],
[
'type' => 'BUTTONS',
'buttons' => [
[
'type' => 'QUICK_REPLY',
'text' => 'Track order'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates"
payload := strings.NewReader("{\n \"template\": {\n \"name\": \"order_shipped\",\n \"category\": \"UTILITY\",\n \"language\": \"en_US\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"format\": \"TEXT\",\n \"text\": \"Your order is on its way\"\n },\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, order {{2}} has shipped.\",\n \"example\": {\n \"body_text\": [\n [\n \"Ana\",\n \"10482\"\n ]\n ]\n }\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Reply STOP to opt out\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Track order\"\n }\n ]\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"template\": {\n \"name\": \"order_shipped\",\n \"category\": \"UTILITY\",\n \"language\": \"en_US\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"format\": \"TEXT\",\n \"text\": \"Your order is on its way\"\n },\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, order {{2}} has shipped.\",\n \"example\": {\n \"body_text\": [\n [\n \"Ana\",\n \"10482\"\n ]\n ]\n }\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Reply STOP to opt out\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Track order\"\n }\n ]\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/inboxes/{inboxId}/message-templates")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"template\": {\n \"name\": \"order_shipped\",\n \"category\": \"UTILITY\",\n \"language\": \"en_US\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"format\": \"TEXT\",\n \"text\": \"Your order is on its way\"\n },\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, order {{2}} has shipped.\",\n \"example\": {\n \"body_text\": [\n [\n \"Ana\",\n \"10482\"\n ]\n ]\n }\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Reply STOP to opt out\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Track order\"\n }\n ]\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "1157693219400316",
"name": "order_shipped",
"language": "en_US",
"category": "UTILITY",
"status": "PENDING"
}{
"error": {
"code": "bad_request",
"message": "The request is malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "This account is suspended."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "template",
"code": "meta_rejected",
"message": "A template with this name already exists. Choose a different name."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}{
"error": {
"code": "service_unavailable",
"message": "WhatsApp did not answer in time. Check the template before retrying: it may already have been submitted."
}
}Authorizations
Headers
Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.
1
Path Parameters
Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.
1
Body
Response
Meta accepted the template for review. It is not usable until its status is approved.
A template accepted by Meta for review.