# WhatsApp messages (/guides/whatsapp)

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`](/api-reference/whatsapp/sendWhatsAppMessage) | Send a message |
| [`GET /api/v1/whatsapp/messages/{message_id}`](/api-reference/whatsapp/getWhatsAppMessage) | Get a message and its status |
| [`GET /api/v1/whatsapp/message-templates`](/api-reference/whatsapp/listWhatsAppTemplates) | List your templates |

Request and response fields are camelCase.

## Before you start [#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`](/errors/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](/authentication)). A read-only key can list templates and read messages, but cannot send.

## The 24-hour window [#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`](/errors/whatsapp_window_closed) and nothing is sent. Send an approved template instead. The window opens again when the customer replies. The [`whatsapp.message.received`](/api-reference/webhooks/onWhatsappMessageReceived) webhook tells you when a customer writes, with `windowOpen` and `serviceWindowExpiresAt`.

## Send a message [#send-a-message]

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
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"] }
    }
  }'
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/whatsapp/messages', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CALLMITRA_API_KEY,
    'Idempotency-Key': 'order-1042-shipped',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+919812345678',
    type: 'template',
    template: {
      name: 'order_update',
      language: 'en',
      values: { body: ['Asha', '#1042'] },
    },
  }),
});
const message = await res.json();
```
</Tab>

<Tab value="Python">
```python
import os
import requests

res = requests.post(
    "https://api.callmitra.ai/api/v1/whatsapp/messages",
    headers={
        "X-API-Key": os.environ["CALLMITRA_API_KEY"],
        "Idempotency-Key": "order-1042-shipped",
    },
    json={
        "to": "+919812345678",
        "type": "template",
        "template": {
            "name": "order_update",
            "language": "en",
            "values": {"body": ["Asha", "#1042"]},
        },
    },
    timeout=30,
)
message = res.json()
```
</Tab>
</Tabs>

Response:

```json
{
  "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 [#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](#list-templates). A missing variable fails with `422` [`parameter_invalid`](/errors/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:

```json
{
  "to": "+919812345678",
  "type": "text",
  "text": "Your order #1042 has shipped."
}
```

### Consent [#consent]

- If the recipient has opted out of your WhatsApp messages, every send fails with `409` [`whatsapp_recipient_opted_out`](/errors/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`](/errors/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`](/errors/whatsapp_marketing_opted_out). Utility and authentication templates still go through.

## Retry safely [#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](/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`](/errors/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`](/errors/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`](/errors/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.

<Callout title="Temporary refusals free the key">
When WhatsApp certainly did not take the message (`429` [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled) or `503` [`whatsapp_upstream_unavailable`](/errors/whatsapp_upstream_unavailable)), the key is released. Wait for the seconds in `Retry-After` and retry with the same key: the retry really sends.
</Callout>

## Message status [#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:

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl https://api.callmitra.ai/api/v1/whatsapp/messages/7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10 \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch(
  `https://api.callmitra.ai/api/v1/whatsapp/messages/${messageId}`,
  { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } },
);
const { status, error } = await res.json();
```
</Tab>

<Tab value="Python">
```python
res = requests.get(
    f"https://api.callmitra.ai/api/v1/whatsapp/messages/{message_id}",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    timeout=30,
)
status = res.json()["status"]
```
</Tab>
</Tabs>

The response has the same shape as the send response. An unknown ID, or a message of another workspace, returns `404` [`resource_not_found`](/errors/resource_not_found).

## List templates [#list-templates]

[`GET /api/v1/whatsapp/message-templates`](/api-reference/whatsapp/listWhatsAppTemplates) 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. |

```bash
curl "https://api.callmitra.ai/api/v1/whatsapp/message-templates?status=APPROVED&category=UTILITY" \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```

```json
{
  "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`](/errors/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`](/errors/whatsapp_template_not_found).

## Receive messages [#receive-messages]

When a customer writes to your number, CallMitra sends the [`whatsapp.message.received`](/api-reference/webhooks/onWhatsappMessageReceived) 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](/webhooks/endpoints) and see all payloads in [Webhook events](/webhooks/events).

## Rate limit [#rate-limit]

Sends are limited to **50 messages per second per workspace**. Above that, a send fails with `429` [`rate_limit_exceeded`](/errors/rate_limit_exceeded) and `Retry-After: 1`. The general API [rate limits](/rate-limits) apply too. WhatsApp's own limits on your number show up as `429` [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled).

## Errors [#errors]

| Status | Code | When |
| --- | --- | --- |
| `404` | [`resource_not_found`](/errors/resource_not_found) | The `contactId` or message ID does not exist in your workspace. |
| `404` | [`whatsapp_template_not_found`](/errors/whatsapp_template_not_found) | No template with that name and language on the sending number's account. |
| `409` | [`whatsapp_number_not_connected`](/errors/whatsapp_number_not_connected) | No connected number, or `phoneId` is not one of your connected numbers. |
| `409` | [`whatsapp_template_not_approved`](/errors/whatsapp_template_not_approved) | The template is not approved. |
| `409` | [`whatsapp_opt_in_required`](/errors/whatsapp_opt_in_required) | Marketing template without a recorded opt-in. |
| `409` | [`whatsapp_recipient_opted_out`](/errors/whatsapp_recipient_opted_out) | The recipient opted out. |
| `409` | [`whatsapp_marketing_opted_out`](/errors/whatsapp_marketing_opted_out) | The recipient stopped marketing messages. |
| `409` | [`whatsapp_window_closed`](/errors/whatsapp_window_closed) | Free-form message outside the 24-hour window. |
| `409` | [`idempotency_key_reused`](/errors/idempotency_key_reused) | Same key, different body (within 24 hours) or different recipient. |
| `409` | [`whatsapp_client_message_id_reused`](/errors/whatsapp_client_message_id_reused) | The key already belongs to a message in another conversation (same customer, another number). |
| `409` | [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress) | The first request with this key is still running. |
| `422` | [`parameter_invalid`](/errors/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`](/errors/rate_limit_exceeded) | More than 50 sends per second. |
| `429` | [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled) | WhatsApp is limiting your number. Nothing was delivered. |
| `503` | [`whatsapp_upstream_unavailable`](/errors/whatsapp_upstream_unavailable) | WhatsApp had a temporary problem. Nothing was delivered. |

For `429` [`whatsapp_upstream_throttled`](/errors/whatsapp_upstream_throttled) and `503` [`whatsapp_upstream_unavailable`](/errors/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](/errors).