Skip to Content
CallMitraDocs

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.

EndpointWhat it does
POST /api/v1/whatsapp/messagesSend a message
GET /api/v1/whatsapp/messages/{message_id}Get a message and its status
GET /api/v1/whatsapp/message-templatesList 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 409 whatsapp_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 typeWhen you can send it
templateAny time. The template must be approved.
text, image, video, audio, document, sticker, interactive, location, contactsOnly 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

FieldTypeDescription
tostringRecipient in international format, for example +919812345678. Up to 32 characters. Send to or contactId.
contactIdstringID of an existing WhatsApp contact, instead of to.
phoneIdstringID 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.
typestringtemplate (the default), text, image, video, audio, document, sticker, interactive, location or contacts.
templateobjectRequired for type: "template". See below.
textstringThe message text for type: "text". Up to 4096 characters. Must not be empty.
mediaobjectRequired for media types (image, video, audio, document, sticker). See below.
contentobjectFor interactive, location or contacts: the object the WhatsApp Cloud API takes under that key.
optInobjectRecords 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:

FieldDescription
nameTemplate name exactly as approved.
languageTemplate language code, for example en or en_US.
valuesValues 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.
componentsAdvanced: 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:

FieldDescription
linkPublic https:// URL of the file. Other schemes fail with 422.
idWhatsApp media ID of a file you already uploaded. Send link or id.
captionCaption shown under an image, video or document. Up to 1024 characters.
filenameFile name shown for a document.

A free-form text message:

{
  "to": "+919812345678",
  "type": "text",
  "text": "Your order #1042 has shipped."
}
  • If the recipient has opted out of your WhatsApp messages, every send fails with 409 whatsapp_recipient_opted_out. Do not retry.
  • A marketing template needs a recorded opt-in. Without one the send fails with 409 whatsapp_opt_in_required. Send optIn with 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 409 whatsapp_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:

  1. 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 with 409 idempotency_key_reused.
  2. 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 (to or contactId), it fails with 409 idempotency_key_reused. If it names the same customer but would go into a different conversation, for example from another of your numbers, it fails with 409 whatsapp_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:

statusMeaning
queuedCreated, not yet handed to WhatsApp.
acceptedWhatsApp accepted the message. wamid is set.
sentWhatsApp sent it.
deliveredIt reached the customer's phone.
readThe customer read it.
failedFinal. WhatsApp refused it; error says why.
unknownWhatsApp 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 parameterDescription
phoneIdOnly templates usable from this sending number.
statusFilter by review status, for example APPROVED. Case does not matter.
categoryMARKETING, UTILITY or AUTHENTICATION.
qPart 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

StatusCodeWhen
404resource_not_foundThe contactId or message ID does not exist in your workspace.
404whatsapp_template_not_foundNo template with that name and language on the sending number's account.
409whatsapp_number_not_connectedNo connected number, or phoneId is not one of your connected numbers.
409whatsapp_template_not_approvedThe template is not approved.
409whatsapp_opt_in_requiredMarketing template without a recorded opt-in.
409whatsapp_recipient_opted_outThe recipient opted out.
409whatsapp_marketing_opted_outThe recipient stopped marketing messages.
409whatsapp_window_closedFree-form message outside the 24-hour window.
409idempotency_key_reusedSame key, different body (within 24 hours) or different recipient.
409whatsapp_client_message_id_reusedThe key already belongs to a message in another conversation (same customer, another number).
409idempotency_request_in_progressThe first request with this key is still running.
422parameter_invalidA field is missing or invalid: to not an international number, empty text, non-https media.link, missing template variable, bad type.
429rate_limit_exceededMore than 50 sends per second.
429whatsapp_upstream_throttledWhatsApp is limiting your number. Nothing was delivered.
503whatsapp_upstream_unavailableWhatsApp 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.

On this page