Chat API

This chapter shows how a website, app, messaging channel or telephony gateway sends a user's text to a bot and gets the reply. It covers POST /api/chat with and without streaming, how sessions and history work, how to end a session so the bot's onSessionEnd hooks run, and the /chat WebSocket. Read it when you connect anything that speaks text to LiteBot. For audio, see Voice.

Endpoints at a glance

The public routes take no credentials. The bot is chosen by botId in the body. Anyone who can reach the port can talk to any active bot and read a session by id, so put LiteBot behind a proxy and limit who reaches it (see Security).

Send a message

POST /api/chat takes a JSON body:

Any other field fails validation.

curl -s -X POST http://127.0.0.1:3345/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"I need an appointment with a dentist","botId":"clinic-reception","userId":"+919876543210","context":{"callerNumber":"+919876543210"}}'

{
  "success": true,
  "data": {
    "response": "Sure. Which day suits you?",
    "sessionId": "sess_mh2k8x1qz4f7a9c",
    "botId": "clinic-reception",
    "shouldEscalate": false,
    "shouldHangup": false,
    "shouldWaitForMore": false,
    "shouldGiveTime": false,
    "skipProcessingSound": false,
    "finishReason": "stop",
    "usage": { "promptTokens": 1450, "completionTokens": 12, "totalTokens": 1462 },
    "toolResults": [],
    "metrics": { "totalTime": 980, "llmTime": 870, "toolsTime": 0, "dbTime": 30, "iterations": 0 }
  }
}

Send sessionId from the first reply with every later message of the same conversation.

Response fields

The non-streaming reply does not carry hangupReason; the streaming metadata does. If you need the reason without streaming, read it from the hangup tool's entry in toolResults.

Streaming

With "stream": true the same endpoint answers 200 with Content-Type: text/plain; charset=utf-8 and chunked transfer encoding. The reply text arrives as it is generated. After the last chunk comes a fixed separator line and one JSON object:

curl -N -s -X POST http://127.0.0.1:3345/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"What are your opening hours?","botId":"clinic-reception","sessionId":"sess_mh2k8x1qz4f7a9c","stream":true}'

We are open 9 am to 6 pm, Monday to Saturday.

--- METADATA ---
{"sessionId":"sess_mh2k8x1qz4f7a9c","botId":"clinic-reception","response":"We are open 9 am to 6 pm, Monday to Saturday.","shouldEscalate":false,"shouldHangup":false,"hangupReason":null,"shouldWaitForMore":false,"shouldGiveTime":false,"skipProcessingSound":false,"finishReason":"stop","usage":{...},"toolResults":[],"metrics":{...}}

Rules for a streaming client:

• Split the body on \n\n--- METADATA ---\n. Everything before it is display text; the JSON after it is the result.
• Treat response in the metadata as the final answer. The engine can change the text after the last chunk, for example to add a handoff line or to blank an incomplete turn.
• If the body ends with \nError: <message> and no metadata, the turn failed. The HTTP status is still 200, because the headers were already sent.
• For a bot with tools, text is held per model call and only the call that ends the turn is streamed, so interim text written next to a tool call never reaches the user. STREAM_HOLD_TOOL_TURNS=false turns that off and streams every call token by token: the first byte is faster, but a voice gateway may speak text that the bot then corrects. Bots without tools always stream token by token.
• A turn that hits the iteration limit can stream nothing. Use response from the metadata.

Sessions and history

A session holds the bot, the user id, the message history and a context object. It is stored in MongoDB (conversations).

• New session. Omit sessionId. The bot's system prompt becomes the first message.
• Your own ids. Send an id LiteBot does not know, and it creates the session under that id. A gateway can use its call id this way.
• History sent to the model. The last LLM_HISTORY_MAX_MESSAGES messages (default 40), trimmed so the window starts at a user turn.
• Context. context keys are merged into the session before the turn runs, so tools see them on the first turn. The model sees them only when the bot has injectContext: true; then LiteBot adds a Current session context: block of key: value lines. Keys that start with _ are not shown to the model.
• Prompt placeholders. {{name}} in a system prompt is filled from the bot's variables when the bot loads, not from context per request. See Bot configuration reference.
• Bot switching. From the third message on, LiteBot checks whether another bot fits the message better and can switch the session to it, even when your request named a botId. The reply's botId shows the switch. Raise the bot's switching threshold if a pinned channel must never switch (see Bots).
• Idle close. A session untouched for SESSION_IDLE_TIMEOUT_MS (default 30 minutes) is closed by a sweep that runs every SESSION_CLEANUP_INTERVAL_MS (default 15 minutes), with reason idle_timeout.

GET /api/chat/session/:sessionId returns a summary, or 404 with "error": "Session not found":

curl -s http://127.0.0.1:3345/api/chat/session/sess_mh2k8x1qz4f7a9c

{
  "success": true,
  "data": {
    "sessionId": "sess_mh2k8x1qz4f7a9c",
    "botId": "clinic-reception",
    "botName": "Clinic Reception",
    "messageCount": 5,
    "status": "active",
    "createdAt": "2026-10-24T09:12:03.120Z",
    "lastActivity": "2026-10-24T09:13:41.552Z",
    "context": { "callerNumber": "+919876543210" },
    "analytics": { "totalCost": 0.0004, "totalTokens": 2930, "messageCount": 2, "toolCallCount": 0, "averageResponseTime": 925, "provider": "gemini", "model": "gemini-2.5-flash" }
  }
}

The full transcript and per-turn traces are under /api/conversations, which needs a login. See Conversations and analytics.

Ending a session

DELETE /api/chat/session/:sessionId closes the session. The reply comes back at once; the bot's onSessionEnd hooks, the analytics summary and the close run in the background, because hooks such as a summary plus a CRM webhook can take ten seconds or more.

curl -s -X DELETE 'http://127.0.0.1:3345/api/chat/session/sess_mh2k8x1qz4f7a9c?reason=remote_hangup'

{ "success": true, "message": "Session ended successfully" }

reason tells the hooks why the session ended. Hooks can filter on it.

Hooks run once per session, only while it is still active, so a gateway DELETE that lands after an llm_hangup does not run them twice. A DELETE for an unknown or already-ended session still answers success: true. The log line Session-end hook ran with success: true means the hook was called; check the tool's own result for the business outcome. Writing hooks is covered in Session-end hooks.

Always send DELETE when your channel knows the conversation is over. Otherwise the session stays active, and the hooks wait, until the idle sweep.

WebSocket chat

ws://127.0.0.1:3345/chat streams replies over one connection. It takes no credentials. Every frame is one JSON object with a type. The largest accepted frame is 1 MB.

On connect the server sends:

{ "type": "connection_established", "connectionId": "3f0c...", "timestamp": "2026-10-24T09:12:00.000Z", "message": "WebSocket connection established successfully" }

Client to server

{ "type": "chat_message", "botId": "clinic-reception", "userId": "web-4821", "message": "Do you open on Sunday?" }

chat_message does not read a context field. If you need per-session context, use POST /api/chat.

Server to client

On the first message of a new session, chat_chunk frames carry the sessionId you sent (none); take the id from chat_response. chat_response has no shouldHangup; a client that needs it reads the hangup tool's entry in toolResults.

Error codes: INVALID_JSON, INVALID_MESSAGE_FORMAT (missing type, unknown type, or chat_message without message), RATE_LIMIT_EXCEEDED, CHAT_PROCESSING_ERROR, SESSION_INIT_ERROR, SESSION_END_ERROR, MESSAGE_PROCESSING_ERROR.

Limits: 30 messages per minute per connection. Every 5 minutes the server pings each connection, terminates one that does not answer within 5 seconds, and closes one idle for 30 minutes with code 1001. Process shutdown closes connections with 1001.

Errors and rate limits

The /api limit is per client IP: 100 requests per 15 minutes when NODE_ENV=production, 500 per 5 minutes otherwise. API_RATE_LIMIT changes the count, not the window. RateLimit-* headers report the state. A gateway or WhatsApp connector sends every user's traffic from one IP, so raise API_RATE_LIMIT to cover its peak, or the whole channel gets 429s. LiteBot trusts one proxy hop (trust proxy is 1), so behind a single reverse proxy the limit applies to the real client address.

Messaging channels such as WhatsApp

A connector that relays WhatsApp or SMS messages calls POST /api/chat once per incoming message.

• Put the sender's phone number in userId. Tools and session-end hooks read the caller's number from userId, because these channels usually send an empty context.
• Keep one sessionId per sender and conversation, for example in the connector's own store. Without it every message starts a new session with no history.
• Send botId on every request so routing does not depend on intent detection.
• End the conversation with DELETE /api/chat/session/:id?reason=<your-reason> when your channel decides it is over, for example after a quiet period, so the hooks run with the full transcript.
• Do not use /api/chat-simple. It is a legacy demo route with a fixed keyword responder: it ignores botId, never calls a model, and keeps sessions in memory only.

Where to go next

• Talk to a bot with audio, or connect the VEXYL gateway: Voice
• Write the hooks that run when a session ends: Session-end hooks
• Read transcripts, traces and costs: Conversations and analytics
• Every other endpoint: HTTP API reference