to number or created, and replies arrive in that user’s conversation through your agent’s normal WhatsApp pipeline. Both endpoints return WHATSAPP_NOT_CONNECTED when the agent has no connected number.
Listing templates
List WhatsApp templates returns every approved template across all of the agent’s WhatsApp Business Accounts, together with the numbers you can send them from.
One Business Account failing does not fail the call, so check
complete before treating the list as the full set.
Selecting a template
Templates are addressed by name.template.language is optional when the name has one approved variant and required when it has several, which otherwise returns TEMPLATE_LANGUAGE_REQUIRED. Unapproved variants never make the choice ambiguous; when none is approved the send returns TEMPLATE_NOT_APPROVED with the review status in details.status.
A template whose buttons take a parameter cannot be sent from this API and returns TEMPLATE_BUTTONS_UNSUPPORTED:
Spot these before sending: in the listing, an unsendable URL button has a
{{...}} placeholder in its url. Campaigns cannot send them either, so edit the template in WhatsApp Manager to use a fixed address, or send a variant without the button.
Templates with an image, video, or document header send the media approved with the template, so there is nothing to supply in the request. MEDIA_UPLOAD_FAILED means that media could not be uploaded to WhatsApp.
Choosing the sender
A template is looked up on the Business Account of the number you send from, so pair the template’s
wabaId with a senders entry carrying the same wabaId. Sending from a number on a different account returns TEMPLATE_NOT_FOUND even though the template exists.
Template variables
Each component numbers its placeholders from{{1}} independently, so values are grouped by component. A template whose header reads Order {{1}} and body reads Hi {{1}}, arriving {{2}} is listed as {"header": ["1"], "body": ["1", "2"]} and takes three values, the header’s 1 being separate from the body’s.
Send back exactly the keys the listing reported. For a named template, use the parameter names in place of the numbers. A value you leave out returns MISSING_TEMPLATE_VARIABLES, and one WhatsApp will not accept, meaning empty or containing a line break, a tab, or five or more consecutive spaces, returns INVALID_TEMPLATE_VARIABLES. Both name each slot as component[key], such as body[2].
Delivery and conversations
Meta accepts sends from a blocked Business Account and drops them afterwards, reporting the reason only on a status webhook. Chatbase checks first, turning that silent loss intoSEND_BLOCKED with the reason in details.reason. It is most often a billing problem: resolve it in WhatsApp Manager and sends resume within about a minute.
A 201 means WhatsApp accepted the message, not that it reached the recipient. It can still be dropped afterwards, most often because the recipient is not on WhatsApp, has blocked your business, or has already had its limit of marketing templates for the period. Match later webhooks against the returned to, which is the canonical WhatsApp id and can differ from what you sent.
conversationId is the conversation the recipient’s replies continue in, and the template is appended to it unless a human has taken the conversation over or it has ended.
Error codes
WhatsApp-specific error codes beyond the standard authentication and rate-limiting errors:| Code | HTTP | Description |
|---|---|---|
WHATSAPP_NOT_CONNECTED | 403 | The agent has no connected WhatsApp number. Connect one from the deploy page. |
PHONE_NUMBER_REQUIRED | 400 | The agent has more than one connected number, so from must say which one sends. |
PHONE_NUMBER_NOT_FOUND | 404 | No number connected to this agent matches from. |
TEMPLATE_NOT_FOUND | 404 | No template with that name, and language when given, exists on the Business Account of the sending number. Check that the template’s wabaId matches the sender’s. |
TEMPLATE_LANGUAGE_REQUIRED | 400 | The template name has more than one approved language variant. Pass template.language. |
TEMPLATE_NOT_APPROVED | 409 | The template exists but has no approved variant to send. details.status carries the Meta review status. |
SEND_BLOCKED | 409 | Meta has blocked business-initiated conversations for this Business Account. details.reason carries Meta’s explanation. |
MISSING_TEMPLATE_VARIABLES | 422 | The template declares variables that were not provided. details.missing lists them as component[key]. |
INVALID_TEMPLATE_VARIABLES | 422 | A value is empty, or contains a line break, a tab, or five or more consecutive spaces. details.invalid names each offending slot and why. |
TEMPLATE_BUTTONS_UNSUPPORTED | 422 | The template has a button that takes a parameter, which this API cannot send. details.buttons lists the button types. |
TEMPLATE_PARAMS_REJECTED | 422 | WhatsApp rejected the parameters as not matching the approved template. |
RECIPIENT_INVALID | 422 | to is not a valid phone number for its country. Unassignable numbers, such as a 555 US area code, are rejected. |
RECIPIENT_NOT_REACHABLE | 422 | WhatsApp reported the recipient as undeliverable. The number may not be on WhatsApp or may have blocked business messages. |
MEDIA_UPLOAD_FAILED | 502 | The template has a media header and uploading its media to WhatsApp failed. |
WHATSAPP_SEND_FAILED | 502 | WhatsApp returned an error that does not map to a more specific code. |