Send a WhatsApp template through the API: the address, the fields, the response and the refusals
The reference for the WhatsApp template address of ArabyBot's API: required and optional fields, an example request and response, every refusal with its code, the request limit, the queue, and the reference that prevents sending twice.
On this page 8
The short answer
With one POST request to the messages/template address of ArabyBot's send API, carrying the recipient's number with its country code, the template name and the values of its variables, with the send key in the header. The response returns the message id and its status: accepted if WhatsApp took it, or queued if it is waiting its turn. Before the request reaches WhatsApp the values are checked against the approved template itself, so a missing one is refused once with a message that names it.
Also asked as: «ازاي ابعت قالب واتساب من السيستم بتاعي» · «ارسال قالب واتساب api» · «ارسال اشعار الطلب على واتساب برمجيا» · «how to send a whatsapp template via api» · «whatsapp template message api example»
The address and authentication
POST https://app.arabybot.com/api/v1/messages/template
Send the send key in the header Authorization: Bearer abk_… or X-Api-Key. You create the key on the «Developer tools» page of the ArabyBot dashboard, and it is shown once when it is made. The call goes from your server, so never put the key in a page a visitor opens or in a mobile app.
The fields
to(required) The recipient's number with its country code, e.g.966501234567.template(required) The template name as it is in WhatsApp. Your template names come back from the templates address.language(optional) The template language, e.g.aroren.variables(optional) The values of the template body's variables, a list by order or by the variables' names.header(optional) The template header's value: the link of the image, video or document, or the text of its variable.buttons(optional) The values of the template's variable buttons, a list.from(optional) The number to send from when the account has more than one; otherwise the default number.reference(optional) A reference from your system, up to a hundred characters, such as the order number plus the notice type. It prevents sending the message twice.
An example request
cURL
curl -X POST https://app.arabybot.com/api/v1/messages/template \
-H "Authorization: Bearer abk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "966501234567",
"template": "order_shipped",
"language": "ar",
"variables": ["Ahmed", "1042"],
"reference": "order-1042-shipped"
}' PHP
$ch = curl_init('https://app.arabybot.com/api/v1/messages/template');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer abk_YOUR_KEY', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'to' => '966501234567',
'template' => 'order_shipped',
'language' => 'ar',
'variables' => ['Ahmed', '1042'],
'reference' => 'order-1042-shipped',
]),
]);
$answer = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch); Python
import requests
r = requests.post(
'https://app.arabybot.com/api/v1/messages/template',
headers={
"Authorization": "Bearer abk_YOUR_KEY",
},
json={
"to": "966501234567",
"template": "order_shipped",
"language": "ar",
"variables": ["Ahmed", "1042"],
"reference": "order-1042-shipped",
},
timeout=30,
)
print(r.status_code, r.json()) Node.js
// Node.js 18+
const r = await fetch('https://app.arabybot.com/api/v1/messages/template', {
method: 'POST',
headers: {"Authorization": "Bearer abk_YOUR_KEY", "Content-Type": "application/json"},
body: JSON.stringify({
"to": "966501234567",
"template": "order_shipped",
"language": "ar",
"variables": [
"Ahmed",
"1042"
],
"reference": "order-1042-shipped"
}),
});
console.log(r.status, await r.json());
The response
200
{ "success": true, "id": 512, "message_id": "wamid.…", "status": "accepted", "to": "966501234567" } idis the message's number on our side; you ask for its status with it later.statusisacceptedif WhatsApp took it, orqueuedif it is waiting in the queue.- If the same reference arrives a second time nothing is sent, and the response returns the first message with
"duplicate": true.
What we measured on this API
One account carries over 99% of these messages; so this is one business's result, not a market rate. The queue sent 224 messages again by itself after a temporary refusal. The most common failure reasons, as Meta returned them:
- Code 131048, in 302 messages.
- Code 130429, in 160 messages.
- Code 131049, in 131 messages.
The refusals
Every refusal comes back as JSON with "success": false, an error_code, and a message in Arabic in message and in English in message_en:
- 422
NO_TEMPLATE: The template name was not put intemplate. - 404
TEMPLATE_NOT_FOUND: No template with this name (and this language, if given) on the number. - 409
TEMPLATE_NOT_APPROVED: The template is in review, rejected or paused; its state is intemplate_status. - 422
BAD_VALUES: A value is missing or does not match the approved template, such as an absent variable or the picture of a picture header. - 409
OPTED_OUT: The customer turned off marketing messages in WhatsApp, so marketing templates cannot reach them. - 400
BAD_JSON: The request body is not valid JSON. - 402
MONTHLY_LIMIT: The account reached its plan's monthly sending limit. - 409
NO_NUMBER: No WhatsApp number is connected to the account, or the number infromis not one of its numbers. - 422
BAD_PHONE: The recipient number is not valid; write it with the country code. - 422
META_REFUSED: WhatsApp refused the message; Meta's code is inmeta_codeand its text inmeta_message. - 503
TRY_AGAIN: WhatsApp is busy or the message could not be recorded for a moment; repeat the same request with the same reference after a minute. - 401
NO_KEY: The key was not sent in the header. - 401
INVALID_KEY: The key is wrong or was revoked; create one under «Developer tools». - 402
SUBSCRIPTION_EXPIRED: The account's subscription has ended. - 403
NOT_IN_PLAN: The account's plan does not include «Developer tools». - 429: The key passed 600 requests a minute; wait the time written in the
Retry-Afterheader. - 500
SERVER: A failure on our side; try again, and tell support if it repeats.
The limits
600 requests a minute per key. Whatever exceeds the pace WhatsApp accepts for your number waits in a queue, comes back with the status queued, then goes out by itself, so no message is lost. Meta's own limits on your number, how many people you may start conversations with in a day and the quality rating, stay as they are behind this API.
The full send API reference · All APIs for developers
Frequently asked questions
Can I send a template that is not approved yet?
No. The request comes back with status 409 and the code TEMPLATE_NOT_APPROVED, and the template's state at Meta is in the template_status field. The template can be sent once it is approved.
How do I stop the message going twice if my system retries?
Send a reference field with every request, holding a stable value from your system such as the order number plus the notice type. If the same reference reaches us again we send nothing and return the first message with duplicate.
Read next
Try the agent before you pay anything
The agent that will answer your customers is the one answering you now: ask it from the chat button here or on WhatsApp. Your account is free with no credit card, and the free trial on your own number or page is activated after you contact our team on customer-service WhatsApp.