Documentation

Send message

POST/api/bot/messages

Body parameters

Parameter	Type	Description
`chatId`*	`string`	The chat to send the message to. Max 64 characters.
`content`*	`string`	Message body. 1 – 5 000 characters.
`type`	`string`= TEXT	Message type. One of TEXT, IMAGE, BUTTON, or QUICK_REPLY.
`metadata`	`object`	Arbitrary JSON payload (max 10 KB). Used for button labels, quick-reply options, etc.

Example request

cURL

curl -X POST https://app.bx-livechat.com/api/bot/messages \
  -H "Authorization: Bearer bxl_pat_aB7XyZ..." \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "clxyz1234567890abc",
    "content": "Hello from my bot!"
  }'

Quick reply example

QUICK_REPLY payload

{
  "chatId": "clxyz1234567890abc",
  "content": "How would you rate your experience?",
  "type": "QUICK_REPLY",
  "metadata": {
    "options": [
      { "label": "Great", "value": "great" },
      { "label": "OK", "value": "ok" },
      { "label": "Poor", "value": "poor" }
    ]
  }
}

Response

200 OK

{
  "id": "msg_newABC123",
  "status": "sent"
}

Side effects

The message is delivered to the visitor in real time via WebSocket.
lastMessageAt on the chat is updated.
firstResponseAt is set if this is the first agent/bot reply.
messageCount on the chat is incremented.
A message.created webhook event is fired (if configured).

Errors

Parameter	Type	Description
`400`	`Bad Request`	Missing or invalid fields. Check chatId length and content size.
`401`	`Unauthorized`	Token is missing, expired, or revoked.
`404`	`Not Found`	The chatId does not exist or does not belong to this organisation.
`500`	`Internal Server Error`	An unexpected error occurred. Retry with exponential back-off.

List chats Upload file