API reference

Chat API

Send a message to one of your bots from your own backend and get the agent's reply. This is the core path for integrating a Hania agent into your product — a help desk, an app, an SMS or WhatsApp flow.

Auth: use an account API key with the chat:send ability (Authorization: Bearer hania_sk_…). This is a server-to-server call — for an in-browser chat experience, use the embeddable widget and a widget key instead, not an account key. See the API overview.

Send a message

POST /api/v1/chat/send — sends a message to a bot and returns its reply in one JSON response.

Request body

Field	Type	Description
`bot_id`	string (uuid)	Required. The bot to message.
`message`	string	Required. The end user's message.
`external_user_id`	string	Your own identifier for the end user, so the conversation is associated with them on your side.
`conversation_id`	string (uuid)	Continue an existing conversation. Omit to let the server resolve or start one.
`new_conversation`	boolean	Start a fresh conversation thread. Defaults to `false`.
`agent_mode`	boolean	Run the bot in agent mode. Defaults to `false`.
`channel`	string	Optional. One of `api`, `sms`, or `whatsapp`.

Example

curl https://app.hania.ai/api/v1/chat/send \
  -H "Authorization: Bearer $HANIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "b1f2c3d4-5678-90ab-cdef-1234567890ab",
    "message": "Where is my October invoice?",
    "external_user_id": "user_8412"
  }'

Response

The reply is returned in the standard envelope:

{
  "success": true,
  "data": {
    "response": "Your October invoice was emailed on Oct 3 and is also in Billing → Invoices.",
    "conversation_id": "c9a8b7c6-1234-4def-89ab-aabbccddeeff",
    "timestamp": "2026-06-09T14:05:22Z"
  },
  "message": ""
}

Persist the returned conversation_id and pass it back as conversation_id on the next message to continue the same thread.

Starting a brand-new conversation returns an instant greeting (the bot's configured opener) without an LLM round-trip, so the first call is fast and isn't metered as a model turn.

Stream a reply

POST /api/v1/chat/send-stream — identical request body and the same chat:send ability, but the reply streams back as Server-Sent Events (Content-Type: text/event-stream) so you can render it token-by-token. The connection closes when the reply is complete.

curl -N https://app.hania.ai/api/v1/chat/send-stream \
  -H "Authorization: Bearer $HANIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bot_id": "b1f2c3d4-…", "message": "Where is my October invoice?" }'

Use /chat/send when you just want the final reply; use /chat/send-stream when you want to show the answer as it's generated.

Billing & limits

Chat is a metered endpoint. If the workspace can't be billed, the call returns 402 with a code of SERVICE_SUSPENDED, PLAN_LIMIT_REACHED, or INSUFFICIENT_BALANCE — surface a "billing needs attention" state to the workspace owner. Standard rate-limit headers and 429 behavior apply as described in the overview.