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.
Download the OpenAPI 3.1 file (Postman, Insomnia)

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.

Header
Authorization: Bearer bx_live_YOUR_KEY

Quick start

  1. Create a key for your agent (link above) and store it on your server.
  2. List the templates you can send: GET /templates. Each says how many values it needs.
  3. Send one: POST /messages/template with the customer’s number and the values, and an Idempotency-Key.
  4. Read its status with GET /messages/{id}. The message is in the agent’s Inbox too.
  5. 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

FieldTypeDescription
typestringone of "template"
torequiredstringThe customer's WhatsApp number with its country code: +919812345678 or 919812345678. max 40 characters
from_phone_number_idstringOptional. 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_datastringOptional. Your own reference (an order id); returned by GET /messages/{id}. max 512 characters
templaterequiredobject
template.namerequiredstring
template.languagerequiredstringThe template's language code as approved (en, en_US, hi).
template.body_valuesstring[]One value per {{n}} in the body, in order.
template.headerobject
template.header.textstringThe header's {{1}}, when it has one.
template.header.media_urlstringhttps:// link to the image, video or document of a media header.
template.button_valuesobjectKeyed 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"
}'
Response 200
{
  "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

FieldTypeDescription
typestringone of "text"
torequiredstringThe customer's WhatsApp number with its country code: +919812345678 or 919812345678. max 40 characters
from_phone_number_idstringOptional. 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_datastringOptional. Your own reference (an order id); returned by GET /messages/{id}. max 512 characters
textrequiredstringmax 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."
}'
Response 200
{
  "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"
    ]
  }
}'
Response 200
{
  "id": "6f1c2a8e-4b1d-4f3a-9c51-2f7d0e9a1b33",
  "status": "sent"
}

Get a message's status

GET/messages/{id}

Response fields

FieldTypeDescription
idstring
statusstringone of "queued", "sent", "delivered", "read", "failed", "unconfirmed"
reasonstringWhy it failed or is unconfirmed.
error_codestringWhatsApp's own error code, when it gave one.
tostring
typestringone of "template", "text"
templatestring
callback_datastring
created_atstring
curl -X GET "https://api.bodhx.ai/api/v1/messages/MESSAGE_ID" \
  -H "Authorization: Bearer bx_live_YOUR_KEY"
Response 200
{
  "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

FieldTypeDescription
namestring
languagestring
categorystring
phone_number_idstring
body_placeholdersinteger
header_typestringone of "TEXT", "IMAGE", "VIDEO", "DOCUMENT", "LOCATION", null
header_placeholdersinteger
buttonsobject[]
curl -X GET "https://api.bodhx.ai/api/v1/templates" \
  -H "Authorization: Bearer bx_live_YOUR_KEY"
Response 200
{
  "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

LimitApplies toWhen exceeded
60 per 1 minute, per keyPOST sends429 rate_limited
300 per 1 minute, per keyGET reads429 rate_limited
2,000 per 1 UTC day, per accountmessages sent429 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.

Error body
{
  "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."
}
HTTPcodeMeaning
400invalid_requestA field is missing or has the wrong form. The message says which.
400not_supportedtype must be "template" or "text".
400agent_has_no_whatsappThe agent has no connected WhatsApp Business (Cloud API) number.
400number_not_on_agentfrom_phone_number_id is not one of this agent's numbers.
400template_not_foundNo template with this name and language on this number.
400template_not_approvedThe template is not approved by WhatsApp.
400template_not_supportedAuthentication (one-time code) templates cannot be sent through this API yet.
400template_params_mismatchThe values do not fit the template. The message says what it needs.
400invalid_number"to" is not a phone number with a country code.
401unauthorizedNo key, or a key that is not valid. Send Authorization: Bearer bx_live_...
401key_revokedThis key was revoked. Create a new one in BodhX.
403insufficient_scopeThe key lacks the permission this endpoint needs.
403account_inactiveThe BodhX account is suspended or deleted.
403agent_not_foundThe agent this key belongs to no longer exists.
403agent_pausedThe agent is paused. Resume it in BodhX.
403send_blockedBodhX's WhatsApp rules did not allow this message to this customer. Nothing was sent.
404message_not_foundNo message with this id for this agent.
409phone_conflictThe number matches a different customer's chat in this account.
409idempotency_conflictAnother request with this Idempotency-Key is being handled. Retry shortly.
409request_in_progressA 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.
422outside_service_windowText only: the customer has not written, in the last 24 hours, to any WhatsApp number this API can send from. Send a template.
422window_closedText 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.
422opted_outThe customer asked not to be messaged (STOP).
422not_on_whatsappWhatsApp reported this number is not on WhatsApp.
422idempotency_key_reusedThis Idempotency-Key was used for a different message.
429rate_limitedToo many requests a minute for this key. Retry shortly.
429daily_limitThis account has sent its messages for today (UTC).
500internal_errorOur fault. Nothing was sent.
502send_failedWhatsApp did not accept the message. It was not sent.
502partially_sentA long text was split and only part of it reached the customer. Do not send the whole message again.
503api_disabledThe Send Message API is switched off for now. Nothing was sent.
503channel_unavailableThe 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.

Send message API reference · BodhX AI