Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.insitechat.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

POST /v1/chatbots/{chatbot_id}/chat
Path parameterTypeRequiredDescription
chatbot_idUUIDyesThe chatbot to message. Must be owned by the API key’s user.

​
Body

FieldTypeRequiredDescription
messagestringyesThe user’s message.
session_idstringnoA session identifier so the chatbot can track conversation history across multiple turns. If omitted, defaults to api-<your-user-id> (so all keyless calls share one conversation per user — usually not what you want for production).

​
Example

curl -X POST https://backend.insitechat.ai/api/v1/chatbots/0a1b2c3d-4e5f-6789-abcd-ef0123456789/chat \
  -H "Authorization: Bearer ic_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is your return policy?",
    "session_id": "user-42-session-abc"
  }'

​
Response

{
  "response": "Our return policy allows returns within 30 days of purchase. Items must be in their original condition with tags attached. To start a return, go to your order history and click \"Request Return\" on the item you'd like to send back."
}
FieldTypeDescription
responsestringThe chatbot’s reply.
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: 
# Turn 1
curl -X POST https://backend.insitechat.ai/api/v1/chatbots/0a1b2c3d-.../chat \
  -H "Authorization: Bearer ic_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is your return policy?", "session_id": "user-42-session-abc"}'

# Turn 2 — same session_id
curl -X POST https://backend.insitechat.ai/api/v1/chatbots/0a1b2c3d-.../chat \
  -H "Authorization: Bearer ic_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Does that apply to sale items too?", "session_id": "user-42-session-abc"}'
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.
StatusWhen
401Missing, invalid, or revoked API key
404No chatbot exists with that UUID or the chatbot belongs to a different user
429Per-key rate limit (API rate limit exceeded. Max 60 requests per minute.) or plan message quota exhausted (e.g. Monthly message limit reached.) — distinguish by reading the detail text
500LLM provider error or internal fault
Every successful chat request counts toward your plan’s monthly message quota. Only role='user' messages count — assistant replies are free. Track usage in Dashboard → Analytics, 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.