> ## Documentation Index > Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp > List the approved WhatsApp templates available to your agent and send them to any phone number. The WhatsApp API [sends approved message templates](/docs/api-v2/whatsapp/send-a-whatsapp-template-message) from the numbers connected to your agent. A template is the only way to open a conversation with someone who has not messaged you in the last 24 hours. Recipients are identified by phone number, with no Chatbase user id needed: a user is resolved from the `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](/docs/api-v2/whatsapp/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. | Field | Meaning | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `templates[].wabaId` | The Business Account the template belongs to. | | `templates[].variables` | The values the template needs, grouped by component. | | `senders[]` | The agent's connected numbers. Each entry carries the `from` value to send with, its `wabaId`, and the display name Meta verified. | | `complete` | `false` when at least one Business Account could not be read. | | `unavailableWabaIds` | The Business Accounts missing from an incomplete listing. Retry to pick them up. | 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`: | Button | Sendable | | ------------------------------------ | -------- | | Quick reply | Yes | | URL with a fixed address | Yes | | URL containing a `{{1}}` placeholder | No | | Copy code | No | | One-time password | No | 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 | `from` | Connected numbers | Result | | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | Omitted | Exactly one | That number sends. | | Omitted | More than one | `PHONE_NUMBER_REQUIRED`. Pick a number from `senders`. | | Provided | Any | Matched on digits, so `+1 415-555-2671` and `14155552671` are equivalent. No match returns `PHONE_NUMBER_NOT_FOUND`. | 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 into `SEND_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](/docs/api-v2/error-handling):
Code HTTP Description
WHATSAPP\_NOT\_CONNECTED403The agent has no connected WhatsApp number. Connect one from the deploy page.
PHONE\_NUMBER\_REQUIRED400The agent has more than one connected number, so from must say which one sends.
PHONE\_NUMBER\_NOT\_FOUND404No number connected to this agent matches from.
TEMPLATE\_NOT\_FOUND404No 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\_REQUIRED400The template name has more than one approved language variant. Pass template.language.
TEMPLATE\_NOT\_APPROVED409The template exists but has no approved variant to send. details.status carries the Meta review status.
SEND\_BLOCKED409Meta has blocked business-initiated conversations for this Business Account. details.reason carries Meta's explanation.
MISSING\_TEMPLATE\_VARIABLES422The template declares variables that were not provided. details.missing lists them as component\[key].
INVALID\_TEMPLATE\_VARIABLES422A 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\_UNSUPPORTED422The template has a button that takes a parameter, which this API cannot send. details.buttons lists the button types.
TEMPLATE\_PARAMS\_REJECTED422WhatsApp rejected the parameters as not matching the approved template.
RECIPIENT\_INVALID422to is not a valid phone number for its country. Unassignable numbers, such as a 555 US area code, are rejected.
RECIPIENT\_NOT\_REACHABLE422WhatsApp reported the recipient as undeliverable. The number may not be on WhatsApp or may have blocked business messages.
MEDIA\_UPLOAD\_FAILED502The template has a media header and uploading its media to WhatsApp failed.
WHATSAPP\_SEND\_FAILED502WhatsApp returned an error that does not map to a more specific code.