Send message API reference
For developers. Setting it up in the dashboard? Read the Send message API guide.
Send WhatsApp messages from your own software
Send WhatsApp templates, and replies inside the 24-hour customer-service window, from the WhatsApp Business number connected to your BodhX AI agent. Every message appears in that agent's Inbox. Your code decides when to send; BodhX applies WhatsApp's rules (approved templates, the 24-hour window, STOP opt-outs) on every send.
- Base URL
https://api.bodhx.ai/api/v1- Sends from
- The WhatsApp Business number connected to the agent the key belongs to. Nothing else: not another agent’s number, not another account’s.
- Format
- JSON in, JSON out, over HTTPS.
Authentication
Every request carries an API key in the Authorization header. A key belongs to ONE agent and sends only from that agent’s number. Only the account owner can make or revoke keys: in Automation › CRM & Software › Receive from your software. A key is shown once; an agent can have two active keys, so you can swap one without downtime. Keep it on your server — never in a website or an app.
Authorization: Bearer bx_live_YOUR_KEYQuick start
- Create a key for your agent (link above) and store it on your server.
- List the templates you can send:
GET /templates. Each says how many values it needs. - Send one:
POST /messages/templatewith the customer’s number and the values, and anIdempotency-Key. - Read its status with
GET /messages/{id}. The message is in the agent’s Inbox too. - When the customer replies, you may answer with text for 24 hours:
POST /messages/text.
Endpoints
Send a template
POST/messages/template
Sends an APPROVED template of this agent's number. Allowed any time, also outside the 24-hour window. One attempt: a send is never repeated by BodhX.
Body
| Field | Type | Description |
|---|---|---|
type | string | one of "template" |
torequired | string | The customer's WhatsApp number with its country code: +919812345678 or 919812345678. max 40 characters |
from_phone_number_id | string | Optional. One of THIS agent's connected numbers (phone_number_id from GET /templates). Default: the agent's first connected number. Another agent's number is refused (number_not_on_agent). |
callback_data | string | Optional. Your own reference (an order id); returned by GET /messages/{id}. max 512 characters |
templaterequired | object | |
template.namerequired | string | |
template.languagerequired | string | The template's language code as approved (en, en_US, hi). |
template.body_values | string[] | One value per {{n}} in the body, in order. |
template.header | object | |
template.header.text | string | The header's {{1}}, when it has one. |
template.header.media_url | string | https:// link to the image, video or document of a media header. |
template.button_values | object | Keyed by button index: the {{1}} of a link button, or a quick-reply payload. |
curl -X POST "https://api.bodhx.ai/api/v1/messages/template" \
-H "Authorization: Bearer bx_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001-confirmed" \
-d '{
"to": "+919812345678",
"template": {
"name": "order_update",
"language": "en",
"body_values": [
"Asha",
"A-1001"
],
"button_values": {
"0": "A-1001"
}
},
"callback_data": "order-1001"
}'{
"id": "6f1c2a8e-4b1d-4f3a-9c51-2f7d0e9a1b33",
"status": "sent"
}Send a text reply
POST/messages/text
Sends free text, only while the customer-service window is open: the customer wrote to this number in the last 24 hours. Otherwise 422 outside_service_window and nothing is sent.
Body
| Field | Type | Description |
|---|---|---|
type | string | one of "text" |
torequired | string | The customer's WhatsApp number with its country code: +919812345678 or 919812345678. max 40 characters |
from_phone_number_id | string | Optional. One of THIS agent's connected numbers. Default: the agent's number the customer last wrote to. A number the customer has not written to in the last 24 hours is refused with 422 window_closed. Another agent's number is refused (number_not_on_agent). |
callback_data | string | Optional. Your own reference (an order id); returned by GET /messages/{id}. max 512 characters |
textrequired | string | max 4096 characters |
curl -X POST "https://api.bodhx.ai/api/v1/messages/text" \
-H "Authorization: Bearer bx_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001-confirmed" \
-d '{
"to": "+919812345678",
"text": "Your order A-1001 is packed and leaves today."
}'{
"id": "6f1c2a8e-4b1d-4f3a-9c51-2f7d0e9a1b33",
"status": "sent"
}Send (type in the body)
POST/messages
The same send as the two endpoints above, with "type": "template" (the default) or "text" in the body.
Body: the template or the text fields above, with type.
curl -X POST "https://api.bodhx.ai/api/v1/messages" \
-H "Authorization: Bearer bx_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001-confirmed" \
-d '{
"type": "template",
"to": "+919812345678",
"template": {
"name": "order_update",
"language": "en",
"body_values": [
"Asha",
"A-1001"
]
}
}'{
"id": "6f1c2a8e-4b1d-4f3a-9c51-2f7d0e9a1b33",
"status": "sent"
}Get a message's status
GET/messages/{id}
Response fields
| Field | Type | Description |
|---|---|---|
id | string | |
status | string | one of "queued", "sent", "delivered", "read", "failed", "unconfirmed" |
reason | string | Why it failed or is unconfirmed. |
error_code | string | WhatsApp's own error code, when it gave one. |
to | string | |
type | string | one of "template", "text" |
template | string | |
callback_data | string | |
created_at | string |
curl -X GET "https://api.bodhx.ai/api/v1/messages/MESSAGE_ID" \
-H "Authorization: Bearer bx_live_YOUR_KEY"{
"id": "6f1c2a8e-4b1d-4f3a-9c51-2f7d0e9a1b33",
"status": "delivered",
"reason": null,
"error_code": null,
"to": "919812345678",
"type": "template",
"template": "order_update",
"callback_data": "order-1001",
"created_at": "2026-11-09T10:15:00.000Z"
}List approved templates
GET/templates
The approved templates of this agent's connected number(s), with how many values each needs.
Each template
| Field | Type | Description |
|---|---|---|
name | string | |
language | string | |
category | string | |
phone_number_id | string | |
body_placeholders | integer | |
header_type | string | one of "TEXT", "IMAGE", "VIDEO", "DOCUMENT", "LOCATION", null |
header_placeholders | integer | |
buttons | object[] |
curl -X GET "https://api.bodhx.ai/api/v1/templates" \
-H "Authorization: Bearer bx_live_YOUR_KEY"{
"templates": [
{
"name": "order_update",
"language": "en",
"category": "UTILITY",
"phone_number_id": "109876543210",
"body_placeholders": 2,
"header_type": null,
"header_placeholders": 0,
"buttons": [
{
"index": 0,
"type": "URL",
"text": "Track",
"needs_value": true
}
]
}
]
}The 24-hour customer-service window
WhatsApp lets a business send free text only within 24 hours of the customer’s last message to that number. Outside it, only an approved template may be sent. BodhX checks this before sending: a text outside the window is refused with 422 outside_service_window, nothing is sent and nothing is counted. A number that has never written to the agent has no window, so its first message must be a template.
Idempotency
Send an Idempotency-Key header with every message, unique per message (your order id plus the event works well). If your request times out and you retry with the same key within 24 hours, you get exactly the first request’s answer back and nothing is sent twice: the same 200, 202 or 502, with the same id. While the first request is still being sent, a repeat answers 409 request_in_progress: retry after a few seconds. When the first attempt sent nothing at all (503 channel_unavailable, 500 internal_error, 403 send_blocked), the key is released, so retrying with it after you fix the cause really sends. The same key with a different message is refused with idempotency_key_reused. BodhX never retries a send itself: an uncertain result is reported as unconfirmed rather than risk a second copy on the customer’s phone.
Rate limits
| Limit | Applies to | When exceeded |
|---|---|---|
| 60 per 1 minute, per key | POST sends | 429 rate_limited |
| 300 per 1 minute, per key | GET reads | 429 rate_limited |
| 2,000 per 1 UTC day, per account | messages sent | 429 daily_limit |
WhatsApp’s own limits on your number (its messaging tier and quality) still apply on top of these.
Errors
Every refusal has the same shape. Branch on code; message is a sentence for a person and may change.
{
"statusCode": 422,
"code": "outside_service_window",
"message": "This customer has not messaged this number in the last 24 hours, so WhatsApp only allows a template. Send an approved template instead."
}| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or has the wrong form. The message says which. |
| 400 | not_supported | type must be "template" or "text". |
| 400 | agent_has_no_whatsapp | The agent has no connected WhatsApp Business (Cloud API) number. |
| 400 | number_not_on_agent | from_phone_number_id is not one of this agent's numbers. |
| 400 | template_not_found | No template with this name and language on this number. |
| 400 | template_not_approved | The template is not approved by WhatsApp. |
| 400 | template_not_supported | Authentication (one-time code) templates cannot be sent through this API yet. |
| 400 | template_params_mismatch | The values do not fit the template. The message says what it needs. |
| 400 | invalid_number | "to" is not a phone number with a country code. |
| 401 | unauthorized | No key, or a key that is not valid. Send Authorization: Bearer bx_live_... |
| 401 | key_revoked | This key was revoked. Create a new one in BodhX. |
| 403 | insufficient_scope | The key lacks the permission this endpoint needs. |
| 403 | account_inactive | The BodhX account is suspended or deleted. |
| 403 | agent_not_found | The agent this key belongs to no longer exists. |
| 403 | agent_paused | The agent is paused. Resume it in BodhX. |
| 403 | send_blocked | BodhX's WhatsApp rules did not allow this message to this customer. Nothing was sent. |
| 404 | message_not_found | No message with this id for this agent. |
| 409 | phone_conflict | The number matches a different customer's chat in this account. |
| 409 | idempotency_conflict | Another request with this Idempotency-Key is being handled. Retry shortly. |
| 409 | request_in_progress | A repeat of an Idempotency-Key whose first request is still being sent. Nothing was sent again; retry after a few seconds to get the first request's answer. |
| 422 | outside_service_window | Text only: the customer has not written, in the last 24 hours, to any WhatsApp number this API can send from. Send a template. |
| 422 | window_closed | Text only: the customer has not written to the sending number in the last 24 hours, but did write to another of this agent's numbers that this API can send from. The message names it and its from_phone_number_id; send from it, or send a template. |
| 422 | opted_out | The customer asked not to be messaged (STOP). |
| 422 | not_on_whatsapp | WhatsApp reported this number is not on WhatsApp. |
| 422 | idempotency_key_reused | This Idempotency-Key was used for a different message. |
| 429 | rate_limited | Too many requests a minute for this key. Retry shortly. |
| 429 | daily_limit | This account has sent its messages for today (UTC). |
| 500 | internal_error | Our fault. Nothing was sent. |
| 502 | send_failed | WhatsApp did not accept the message. It was not sent. |
| 502 | partially_sent | A long text was split and only part of it reached the customer. Do not send the whole message again. |
| 503 | api_disabled | The Send Message API is switched off for now. Nothing was sent. |
| 503 | channel_unavailable | The agent's WhatsApp number cannot send right now. Reconnect it in BodhX. |
Message status and webhooks
GET /messages/{id} moves through queued → sent → delivered → read, or ends failed (with reason and WhatsApp’s error_code) or unconfirmed (the send may have landed; it is never repeated). Put your own reference in callback_data to match a message to your order.
Status webhooks (BodhX calling your URL, signed with HMAC-SHA256) are not available yet. Until then, read the status with the GET above.
Try it
Try it sends a real test message from your agent’s number to your own phone, so it runs inside your account. Sign in to open it with your agents.
