WhatsApp APIAPI
WhatsApp: send templates through the API
List the approved templates of each number and send a WhatsApp template through the XBASE API, at any time, with examples and errors.
Updated on
A template is a message approved by Meta that can be sent at any time, including to someone who never talked to the business or outside the 24-hour window. Templates are created and approved in WhatsApp API → Templates.
List the templates
GET https://api.xbase.app/api/external/v1/whatsapp/templates?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3bnumberId is optional: without it, you get the templates of every number in the workspace. With it, you get the templates of the number and the ones not linked to any number.
curl "https://api.xbase.app/api/external/v1/whatsapp/templates?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
-H "Authorization: Bearer $XBASE_API_KEY"Response 200:
[
{
"id": "0f4c8e2a-1b3d-4e5f-8a9b-7c6d5e4f3a2b",
"numberId": "6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b",
"name": "order_delivered",
"language": "en_US",
"category": "UTILITY",
"status": "APPROVED",
"body": "Hi {{1}}, your order {{2}} was delivered on {{3}}.",
"paramsCount": 3,
"headerFormat": null
}
]| Field | Type | Description |
|---|---|---|
id | text | Template id. Can go in template.id when sending |
numberId | text or null | Number that owns the template: the template only goes out through it. null: the template is not linked to a number and goes out through the number chosen in the send |
name | text | Template name at Meta |
language | text or null | Language, like en_US |
category | text or null | MARKETING, UTILITY or AUTHENTICATION |
status | text | Status at Meta. Only APPROVED can be sent |
body | text or null | Text with the variables {{1}}, {{2}}… |
paramsCount | number | How many variables the text has: the size of template.params |
headerFormat | text or null | Template header. IMAGE, VIDEO and DOCUMENT require template.headerMediaUrl when sending |
Send a template
POST https://api.xbase.app/api/external/v1/whatsapp/templates| Field | Type | Required | Rule |
|---|---|---|---|
numberId | text | yes | Sending number (list the numbers) |
to | text | yes | Contact phone with the country code, 8 to 15 digits. +, spaces, hyphens and parentheses are removed |
template.name | text | one of the two | Template name, as in the list |
template.id | text | one of the two | Template id, as in the list |
template.language | text | no | Template language, like pt_BR (the default). Only with template.name |
template.params | list of texts | no | Values of {{1}}, {{2}}…, in order. Up to 30, each up to 1,024 characters |
template.headerMediaUrl | text | with a media header | Public https URL of the header image, video or document |
curl -X POST https://api.xbase.app/api/external/v1/whatsapp/templates \
-H "Authorization: Bearer $XBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"numberId": "6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b",
"to": "15555550100",
"template": {
"name": "order_delivered",
"language": "en_US",
"params": ["Mary", "12345", "Nov 4 at 2:28 PM"]
}
}'Response 200:
{
"status": "accepted",
"messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABEYEjQ1QzM1RkQ2RDhGNjZBMDQ3MwA=",
"threadId": "c1d7f0b2-5a4e-4f3d-9c2b-1a0e9d8c7b6a",
"dialogId": "5a0e4c31-7b2d-4e8f-a1c3-9d6b5e4f3a21"
}| Field | Description |
|---|---|
status | accepted: Meta accepted the send. Delivery to the phone comes later, in the webhook events |
messageId | Message id at Meta (wamid.…), the same as in the delivery and read events |
threadId | The contact's conversation at XBASE |
dialogId | Message in the conversation |
Parameter rules
- Send the parameters as text, in the order of the variables and in the amount of
paramsCount. With the wrong amount, the response is 422SEND_REJECTED, saying how many variables the template expects. - A template with variables linked to conversation data (set up in WhatsApp API → Templates) can go without
params: XBASE fills them with the contact and conversation data. - Meta rejects a parameter with a line break, a tab or more than 4 spaces in a row (422
META_ERROR).
What happens after the send
- XBASE creates the contact if it does not exist yet, opens or reuses its conversation with the number and records the template sent.
- The message shows up in the Chatcenter. Delivery and read come through the workspace webhooks.
- When the contact replies, the 24-hour window opens and you can send free-form messages.
- The API does not prevent duplicate sends: repeating the same call sends the template again.
Send errors
| Status | code | When |
|---|---|---|
| 400 | (no code) | Invalid field. The message says which one, like to: telefone inválido |
| 404 | NUMBER_NOT_FOUND | The number does not exist in this workspace |
| 404 | TEMPLATE_NOT_FOUND | The template does not exist for this number: check the name, the language and the numberId |
| 422 | NUMBER_DISCONNECTED | The number is disconnected |
| 422 | SEND_REJECTED | XBASE refused before sending: missing or extra variables, or the header media is missing. The message says why |
| 422 | META_ERROR | Meta refused, for example, a paused or unapproved template. details.metaCode has Meta's code |
See the full format in Errors.