Messages

Send and receive messages across all connected channels. The Messages API provides a unified interface regardless of whether the message goes via WhatsApp, web chat, or email.

Send a Message

POST/v1/messages

Send a message to a customer on any connected channel. HanDl automatically routes the message through the correct channel based on the conversation context.

Parameter	Type	Description
conversation_id Required	string	The conversation to send the message in.
body Required	string	The message content. Supports plain text. Max 4096 characters.
type Optional	string	Message type: 'text', 'image', 'template'. Defaults to 'text'.
media_url Optional	string	URL of the media attachment. Required when type is 'image'.
metadata Optional	object	Arbitrary key-value pairs to attach to the message.

curl

curl -X POST https://api.handl-ng.com/v1/messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_8xk2m",
    "body": "Hi! Your order #1042 has been shipped 🚚",
    "metadata": {
      "order_id": "ord_abc123"
    }
  }'

javascript

const res = await fetch('https://api.handl-ng.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    conversation_id: 'conv_8xk2m',
    body: 'Hi! Your order #1042 has been shipped 🚚',
    metadata: { order_id: 'ord_abc123' },
  }),
});

const message = await res.json();
console.log(message.id); // "msg_xyz789"

Response

json

{
  "id": "msg_xyz789",
  "object": "message",
  "conversation_id": "conv_8xk2m",
  "body": "Hi! Your order #1042 has been shipped 🚚",
  "type": "text",
  "direction": "outbound",
  "channel": "whatsapp",
  "status": "sent",
  "metadata": {
    "order_id": "ord_abc123"
  },
  "created_at": "2025-06-15T14:30:00Z"
}

List Messages

GET/v1/messages

Retrieve messages, optionally filtered by conversation.

Parameter	Type	Description
conversation_id Optional	string	Filter by conversation.
direction Optional	string	'inbound' or 'outbound'.
limit Optional	integer	Number of results (1–100). Default 25.
starting_after Optional	string	Cursor for pagination. Pass the last message ID.

curl

curl "https://api.handl-ng.com/v1/messages?conversation_id=conv_8xk2m&limit=10" \
  -H "Authorization: Bearer sk_live_..."

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "msg_xyz789",
      "body": "Hi! Your order #1042 has been shipped 🚚",
      "direction": "outbound",
      "status": "delivered",
      "created_at": "2025-06-15T14:30:00Z"
    }
  ],
  "has_more": true
}

Retrieve a Message

GET/v1/messages/:id

curl

curl https://api.handl-ng.com/v1/messages/msg_xyz789 \
  -H "Authorization: Bearer sk_live_..."

ℹ️

Messages sent via the API appear in your Conversations inbox just like any other message. Your AI agent and team can see and respond to them.

Message Statuses

queuedMessage accepted by HanDl, waiting to be sent to the channel

sentMessage delivered to the channel provider (e.g., WhatsApp)

deliveredMessage confirmed delivered to the recipient

readRecipient has read the message (channel-dependent)

failedMessage could not be delivered. Check the error field.