WhatsApp messages
Send WhatsApp template and session messages from your systems, track delivery, and list your templates.
The WhatsApp API sends messages from your connected WhatsApp Business number. You can send approved templates at any time and free-form messages while the customer's 24-hour window is open. You can also read a message's delivery status and list your templates.
| Endpoint | What it does |
|---|---|
POST /api/v1/whatsapp/messages | Send a message |
GET /api/v1/whatsapp/messages/{message_id} | Get a message and its status |
GET /api/v1/whatsapp/message-templates | List your templates |
Request and response fields are camelCase.
Before you start
- Connect a number. Connect your WhatsApp Business number in the console under WhatsApp → Numbers. Until a number is connected, sends fail with
409whatsapp_number_not_connected. - Get templates approved. Create templates in WhatsApp Manager or the console. A template created in WhatsApp Manager shows up in the API after a template sync in the console.
- Use an API key with WhatsApp access. A key limited to resources needs WhatsApp (Authentication). A read-only key can list templates and read messages, but cannot send.
The 24-hour window
WhatsApp decides what you may send by the customer service window:
Message type | When you can send it |
|---|---|
template | Any time. The template must be approved. |
text, image, video, audio, document, sticker, interactive, location, contacts | Only within 24 hours of the customer's last message to that number. |
Outside the window a free-form send fails with 409 whatsapp_window_closed and nothing is sent. Send an approved template instead. The window opens again when the customer replies. The whatsapp.message.received webhook tells you when a customer writes, with windowOpen and serviceWindowExpiresAt.
Send a message
curl -X POST https://api.callmitra.ai/api/v1/whatsapp/messages \
-H "X-API-Key: $CALLMITRA_API_KEY" \
-H "Idempotency-Key: order-1042-shipped" \
-H "Content-Type: application/json" \
-d '{
"to": "+919812345678",
"type": "template",
"template": {
"name": "order_update",
"language": "en",
"values": { "body": ["Asha", "#1042"] }
}
}'Response:
{
"id": "7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10",
"wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQ0Y2",
"status": "accepted",
"conversationId": "0b6f2a8e-4c1d-4f7a-8f53-6a1c9e2d7b44",
"error": null,
"createdAt": "2026-01-15T09:30:00+00:00"
}Keep id. You need it to read the message later.
Request body
| Field | Type | Description |
|---|---|---|
to | string | Recipient in international format, for example +919812345678. Up to 32 characters. Send to or contactId. |
contactId | string | ID of an existing WhatsApp contact, instead of to. |
phoneId | string | ID of your sending WhatsApp number. Leave it out to send from your default number. An ID that is not a valid UUID fails with 422; it never falls back to the default number. |
type | string | template (the default), text, image, video, audio, document, sticker, interactive, location or contacts. |
template | object | Required for type: "template". See below. |
text | string | The message text for type: "text". Up to 4096 characters. Must not be empty. |
media | object | Required for media types (image, video, audio, document, sticker). See below. |
content | object | For interactive, location or contacts: the object the WhatsApp Cloud API takes under that key. |
optIn | object | Records the recipient's opt-in with this send: source (required, up to 64 characters, for example checkout) and text (the consent wording the customer agreed to, up to 2000 characters). |
template:
| Field | Description |
|---|---|
name | Template name exactly as approved. |
language | Template language code, for example en or en_US. |
values | Values for the template's variables: body as a list in order (or an object keyed by placeholder, such as {"1": "Asha"}), plus header and buttons when the template has them. |
components | Advanced: WhatsApp Cloud API components, sent as-is instead of values. |
Find name and language with List templates. A missing variable fails with 422 parameter_invalid on template.values.
media:
| Field | Description |
|---|---|
link | Public https:// URL of the file. Other schemes fail with 422. |
id | WhatsApp media ID of a file you already uploaded. Send link or id. |
caption | Caption shown under an image, video or document. Up to 1024 characters. |
filename | File name shown for a document. |
A free-form text message:
{
"to": "+919812345678",
"type": "text",
"text": "Your order #1042 has shipped."
}Consent
- If the recipient has opted out of your WhatsApp messages, every send fails with
409whatsapp_recipient_opted_out. Do not retry. - A marketing template needs a recorded opt-in. Without one the send fails with
409whatsapp_opt_in_required. SendoptInwith the message to record consent you collected, or use a utility or authentication template. - If the customer turned off promotional messages in WhatsApp, marketing templates fail with
409whatsapp_marketing_opted_out. Utility and authentication templates still go through.
Retry safely
Send an Idempotency-Key header with every send. Create it once per message and reuse it on every retry of that message. CallMitra checks it in two ways:
- For 24 hours, the standard idempotency rules apply. The same key with the same body returns the first response again, with the header
Idempotent-Replayed: true. The same key with a different body fails with409idempotency_key_reused. - Permanently, CallMitra also stores the key on the message itself, once per workspace. A retry after 24 hours, or while the idempotency store is unavailable, does not send again. It returns the message that was already sent, with its current
status. If that retry names a different recipient (toorcontactId), it fails with409idempotency_key_reused. If it names the same customer but would go into a different conversation, for example from another of your numbers, it fails with409whatsapp_client_message_id_reused. In both cases nothing is sent; use a new key for each new message.
There is no separate clientMessageId field in the request body. The Idempotency-Key header is the only way to make a send retry-safe.
Temporary refusals free the key
When WhatsApp certainly did not take the message (429 whatsapp_upstream_throttled or 503 whatsapp_upstream_unavailable), the key is released. Wait for the seconds in Retry-After and retry with the same key: the retry really sends.
Message status
status moves forward as WhatsApp reports progress:
status | Meaning |
|---|---|
queued | Created, not yet handed to WhatsApp. |
accepted | WhatsApp accepted the message. wamid is set. |
sent | WhatsApp sent it. |
delivered | It reached the customer's phone. |
read | The customer read it. |
failed | Final. WhatsApp refused it; error says why. |
unknown | WhatsApp did not answer clearly. A later status update settles it. |
If WhatsApp refuses a message after CallMitra created it, the send still returns 200, with status: "failed" and an error object holding WhatsApp's code and message. Check status on every 200.
Read the current status with the id from the send:
curl https://api.callmitra.ai/api/v1/whatsapp/messages/7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10 \
-H "X-API-Key: $CALLMITRA_API_KEY"The response has the same shape as the send response. An unknown ID, or a message of another workspace, returns 404 resource_not_found.
List templates
GET /api/v1/whatsapp/message-templates returns up to 500 templates, sorted by name and language. Deleted templates are left out.
| Query parameter | Description |
|---|---|
phoneId | Only templates usable from this sending number. |
status | Filter by review status, for example APPROVED. Case does not matter. |
category | MARKETING, UTILITY or AUTHENTICATION. |
q | Part of the template name. |
curl "https://api.callmitra.ai/api/v1/whatsapp/message-templates?status=APPROVED&category=UTILITY" \
-H "X-API-Key: $CALLMITRA_API_KEY"{
"templates": [
{
"id": "4a9e7c21-3b5d-4f1e-8c2a-9d6b0e1f2a34",
"name": "order_update",
"language": "en",
"category": "UTILITY",
"status": "APPROVED",
"qualityScore": "GREEN",
"rejectedReason": null,
"parameterFormat": "POSITIONAL",
"components": [
{ "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped." }
],
"lastSyncedAt": "2026-01-15T08:00:00+00:00"
}
]
}Only APPROVED templates can be sent. Sending any other fails with 409 whatsapp_template_not_approved, and the message names the current status. A name and language pair that does not exist on the sending number's account fails with 404 whatsapp_template_not_found.
Receive messages
When a customer writes to your number, CallMitra sends the whatsapp.message.received webhook event. It includes the contact (with its id, which you can send back as contactId), the conversation, the sending number's phoneId and the message. Set up an endpoint in Webhooks and see all payloads in Webhook events.
Rate limit
Sends are limited to 50 messages per second per workspace. Above that, a send fails with 429 rate_limit_exceeded and Retry-After: 1. The general API rate limits apply too. WhatsApp's own limits on your number show up as 429 whatsapp_upstream_throttled.
Errors
| Status | Code | When |
|---|---|---|
404 | resource_not_found | The contactId or message ID does not exist in your workspace. |
404 | whatsapp_template_not_found | No template with that name and language on the sending number's account. |
409 | whatsapp_number_not_connected | No connected number, or phoneId is not one of your connected numbers. |
409 | whatsapp_template_not_approved | The template is not approved. |
409 | whatsapp_opt_in_required | Marketing template without a recorded opt-in. |
409 | whatsapp_recipient_opted_out | The recipient opted out. |
409 | whatsapp_marketing_opted_out | The recipient stopped marketing messages. |
409 | whatsapp_window_closed | Free-form message outside the 24-hour window. |
409 | idempotency_key_reused | Same key, different body (within 24 hours) or different recipient. |
409 | whatsapp_client_message_id_reused | The key already belongs to a message in another conversation (same customer, another number). |
409 | idempotency_request_in_progress | The first request with this key is still running. |
422 | parameter_invalid | A field is missing or invalid: to not an international number, empty text, non-https media.link, missing template variable, bad type. |
429 | rate_limit_exceeded | More than 50 sends per second. |
429 | whatsapp_upstream_throttled | WhatsApp is limiting your number. Nothing was delivered. |
503 | whatsapp_upstream_unavailable | WhatsApp had a temporary problem. Nothing was delivered. |
For 429 whatsapp_upstream_throttled and 503 whatsapp_upstream_unavailable, detail holds the message record with retryable: true. Retry after Retry-After with the same Idempotency-Key. Every error uses the standard error envelope.