Skip to main content
The InsiteChat Chat API runs your message through the same RAG pipeline as the web embed — hybrid vector + BM25 retrieval with Reciprocal Rank Fusion, system prompt, identity rules, and conversation history — then returns the chatbot’s reply as a single JSON response. Streaming is not supported.

Send a Message

Request

Body

Example

Response

The endpoint does not return a conversation_id — the conversation is keyed by your session_id. If you need to correlate the reply with a server-side conversation record, subscribe to the conversation.started webhook.

Multi-Turn Conversations

Pass the same session_id on every call to give the chatbot the last 10 turns of history:
Use one session_id per end-user session (e.g. derived from your own user ID + a UUID per visit). Without a session_id, every request shares one default per-key conversation, which mixes up history.

Error Responses

Error bodies use Django Ninja’s default {"detail": "..."} shape — no machine-readable code field.
Every successful chat request counts toward your plan’s monthly message quota. Only role='user' messages count — assistant replies are free. Track usage in DashboardAnalytics, or upgrade your plan in Plans & Pricing.

What Happens Under the Hood

Each call:
  1. Enforces your plan’s monthly message quota and per-conversation rate limit (raises 429 if exceeded).
  2. Looks up or creates a Conversation keyed by (chatbot_id, session_id).
  3. If a human agent has taken over this conversation, persists the inbound message but skips LLM generation (no reply is returned in that case — the dashboard surfaces it for the agent).
  4. Saves the user message and fires the conversation.started webhook (if newly created) and message.received webhook.
  5. Retrieves relevant context via hybrid vector + BM25 search with RRF fusion.
  6. Builds the prompt (your chatbot’s system prompt + identity rules + retrieved context + last 10 turns).
  7. Calls the configured LLM provider (Gemini / OpenAI / Ollama) and saves + returns the reply.