What this does
The Chat API lets a bot or external automation post a message into an existing inbox conversation — the multi-channel inbox that powers Helpdesk and the chatbot widget. Use it to relay agent replies from outside the dashboard (e.g. WhatsApp, internal chat, an LLM workflow).
Conversations are not created via this endpoint — they originate from the channel side (web widget, WhatsApp, email, SMS, etc.) and become addressable by conversation_id once the system has them. Listing and reading conversations is a separate concern; v1 currently exposes only the write side.
When to use it
- Post an agent reply into an active inbox conversation.
- Add an internal note (
sender_type: "note") that customers never see. - Forward an LLM-drafted reply that a human reviewed.
Authentication and scopes
Requests must include Authorization: Bearer <key>. The endpoint requires:
chat:write— send a message into a conversation
Endpoints
Send a message
POST /api/v1/chat/:conversation_id/send
{
"body": "I've checked your order — dispatching today.",
"sender_type": "agent"
}
body is required (trimmed; empty messages are rejected). sender_type is optional and defaults to "agent"; pass "note" for an internal-only note. Optional fields: attachment_url (string), metadata (object).
The message is sent on the conversation's existing channel (web/whatsapp/email/sms/facebook/instagram/voice) — you don't pick the channel; it's inherited. Downstream side-effects fire as normal: SSE broadcast, CRM event-bus emit.
Response (201 Created): the created connect_messages row.
Errors:
| Code | Status | Meaning |
|---|---|---|
| not_found | 404 | No conversation with that id in this entity |
| missing_field | 400 | body missing or whitespace-only |
| invalid_body | 400 | Request body was not valid JSON |
| chat_write_denied | 403 | API key lacks chat:write |
| missing_api_key / invalid_api_key | 401 | Bearer token missing or invalid |