Skip to Content
CallMitraDocs
API referenceWhatsapp

Send a WhatsApp message

Sends a template, text, media, interactive, location or contacts message to `to` (or `contactId`) from `phoneId` or your default number. Templates can be sent any time; every other type needs the customer to have messaged you in the last 24 hours. A refusal by WhatsApp after the message was created returns 200 with `status: failed` and `error`; a temporary refusal returns 429 or 503 with `Retry-After`, and nothing was delivered.

POST
/api/v1/whatsapp/messages

Sends a template, text, media, interactive, location or contacts message to to (or contactId) from phoneId or your default number. Templates can be sent any time; every other type needs the customer to have messaged you in the last 24 hours. A refusal by WhatsApp after the message was created returns 200 with status: failed and error; a temporary refusal returns 429 or 503 with Retry-After, and nothing was delivered.

Authorization

headerX-API-Key<token>

Create in the console: Settings → API & webhooks.

Header Parameters

Idempotency-Key?string

Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice.

Lengthlength <= 255

Request Body

application/json
  1. body
contactId?Contactid

Id of an existing WhatsApp contact, instead of to.

Default""
content?Content

For interactive, location or contacts: the object the WhatsApp Cloud API takes under that key.

media?|

Required for media types: link or id.

optIn?|

Record the recipient's opt-in with this send (needed before marketing templates).

phoneId?Phoneid

Your sending WhatsApp number's id. Leave out to use your default number.

Default""
template?|

Required for type=template.

text?Text

Message text for type=text.

Lengthlength <= 4096
Default""
to?To

Recipient in international format, e.g. +919812345678. Or send contactId.

Lengthlength <= 32
Default""
type?Type

template, text, image, video, audio, document, sticker, interactive, location or contacts. Everything except template needs an open 24-hour window.

Default"template"

Response Body

OK

application/json
  1. response
conversationId*Conversationid

The WhatsApp conversation the message belongs to.

createdAt*|

When the message was created (ISO 8601).

error*|

Why WhatsApp refused the message, when status is failed.

id*Id

Message id. Use it with GET /whatsapp/messages/{messageId}.

status*Status

queued → accepted → sent → delivered → read; failed is final. unknown means WhatsApp did not answer clearly; a later status update settles it.

wamid*|

WhatsApp's message id once WhatsApp accepted the message.

[key: string]?any
Example Request
curl -X POST 'https://api.callmitra.ai/api/v1/whatsapp/messages' \  -H 'Content-Type: application/json' \  -d '{  "template": {    "language": "en",    "name": "order_update",    "values": {      "body": [        "Asha",        "#1042"      ]    }  },  "to": "+919812345678",  "type": "template"}'
Example Response
{  "conversationId": "0b6f2a8e-4c1d-4f7a-8f53-6a1c9e2d7b44",  "createdAt": "2026-01-15T09:30:00+00:00",  "id": "7d3c1a52-9f0e-4b8e-9a59-2f4f3c6b1e10",  "status": "accepted",  "wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQ0Y2"}