Messaging

The Messaging API exposes your business’s WhatsApp inbox: read conversations and their message history, and send text or template messages to customers.

All endpoints share the prefix /v1/messaging and authenticate with an API key.

Endpoint	Scope
`GET /v1/messaging/conversations`	`messaging:conversations:read`
`GET /v1/messaging/conversations/:id`	`messaging:messages:read`
`POST /v1/messaging/conversations/:id/messages`	`messaging:messages:send`
`POST /v1/messaging/messages/template`	`messaging:messages:send`

Sends are subject to WhatsApp’s messaging rules. Outside the 24-hour customer service window you must use an approved template - see Send a template.

List conversations


GET /v1/messaging/conversations

Returns conversations for your business, most recently active first.

Query parameters

Parameter	Type	Description
`status`	string	Filter by conversation status (e.g. `open`, `pending_customer`)
`mode`	string	Filter by `ai` or `human` handling
`assigned`	string	`me` or `unassigned`
`search`	string	Match against customer name or phone


{
  "message": "Conversations retrieved",
  "data": [
    {
      "id": "cv1a2b3c-...",
      "businessId": "b1a2c3d4-...",
      "customerPhone": "+2348012345678",
      "customerName": "Ada Lovelace",
      "status": "open",
      "mode": "ai",
      "unreadCount": 1,
      "lastInboundAt": "2026-01-15T09:58:00.000Z",
      "lastOutboundAt": "2026-01-15T09:59:00.000Z"
    }
  ]
}

Get a conversation


GET /v1/messaging/conversations/:id

Returns a single conversation with its most recent messages (newest first).


{
  "message": "Conversation retrieved",
  "data": {
    "id": "cv1a2b3c-...",
    "customerPhone": "+2348012345678",
    "customerName": "Ada Lovelace",
    "status": "open",
    "messages": [
      {
        "id": "m1a2b3c4-...",
        "direction": "inbound",
        "messageType": "text",
        "text": "Is my order shipped?",
        "deliveryStatus": "delivered",
        "createdAt": "2026-01-15T09:58:00.000Z"
      }
    ]
  }
}

Send a text message


POST /v1/messaging/conversations/:id/messages

Sends a free-form text message in an existing conversation. Only valid inside WhatsApp’s 24-hour customer service window; outside it, send a template instead.

Body

Field	Type	Required	Description
`text`	string	Yes	Message body (1–4096 characters)


{ "text": "Your order #1234 shipped today and arrives Friday." }

Response 201 Created - the created outbound message.


{
  "message": "Message sent",
  "data": {
    "id": "m2a2b3c4-...",
    "conversationId": "cv1a2b3c-...",
    "direction": "outbound",
    "messageType": "text",
    "text": "Your order #1234 shipped today and arrives Friday.",
    "deliveryStatus": "sent",
    "createdAt": "2026-01-15T10:01:00.000Z"
  }
}

Send a template


POST /v1/messaging/messages/template

Sends an approved WhatsApp template to a phone number, starting a new conversation if one doesn’t already exist. Use this to message customers outside the service window.

Body

Field	Type	Required	Description
`business_whatsapp_number_id`	uuid	Yes	The WhatsApp number to send from
`phone`	string	Yes	Destination number in E.164
`template_key`	string	Yes	The approved template to send
`customer_name`	string	No	Name for a newly created contact/conversation
`variables`	object	No	Key/value map filling the template’s placeholders


{
  "business_whatsapp_number_id": "wn1a2b3c-...",
  "phone": "+2348012345678",
  "template_key": "order_shipped",
  "customer_name": "Ada Lovelace",
  "variables": { "order_id": "1234", "eta": "Friday" }
}

Response 201 Created - the created template message.

Both send endpoints support idempotency. Pass an Idempotency-Key header so a retry never sends a duplicate message.