Chat & widget

Chat (text)

Run any assistant as a text chatbot — same brain (prompt, knowledge, tools) as voice, delivered as chat. Conversations are stored server-side; send a message and get a reply as JSON or as a token-by-token SSE stream. Replies use the assistant's Query/API tools automatically and return grounded citations.

Streaming (SSE)

Send Accept: text/event-stream (or ?stream=true) on the send-message endpoint. Events: message.created → tool.call / tool.result (when the assistant uses a tool) → content.delta (tokens) → message.completed (usage + cost + citations), terminated by data: [DONE].

bash

curl -N -X POST https://api.bolchoai.in/v1/conversations/$CONV_ID/messages \
  -H "Authorization: Bearer $BOLCHO_API_KEY" -H "Content-Type: application/json" -H "Accept: text/event-stream" \
  -d '{ "content": "What is the price of a CBC test?" }'

Idempotency

Pass an Idempotency-Key header to make retries safe (the stored response is replayed). Additionally, give each user message a clientMessageId — resending the same id never re-runs or double-charges; the stored answer is returned.

Cost: chat runs a cost-efficient text model on your assistant's provider and every reply is metered against workspace credits. Each conversation and message records its exact token usage and cost.

POST/chat chat:write

One-shot chat

Create-or-continue in one call: pass agentId to start (returns conversationId) or conversationId to continue. Supports streaming.

Body

agentId	uuid	Required when starting a new conversation.
conversationId	uuid	Continue an existing conversation.
content*	string	The user's message.
endUser	object	Your end-user identity: { externalId, name?, email?, phone? }.
stream	boolean	Stream the reply as SSE.

bash

curl -X POST https://api.bolchoai.in/v1/chat -H "Authorization: Bearer $BOLCHO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "agentId": "'$AGENT_ID'", "content": "Do you ship to Canada?" }'

Response

json

{ "conversationId": "…", "message": { "id": "…", "role": "assistant", "content": "Yes — …", "citations": [ { "kbName": "Docs", "documentTitle": "shipping.pdf", "snippet": "…" } ] }, "usage": { "inputTokens": 812, "outputTokens": 96, "costUsd": 0.00021 }, "status": "open" }

POST/conversations chat:write

Create conversation

Start a server-stored conversation with an assistant. The assistant's published version is pinned at creation.

Body

agentId*	uuid	The assistant to chat with.
endUser	object	Your end-user: { externalId, name?, email?, phone? } — dedupes across conversations.
clientRef	string	Your own thread id for correlation.
metadata	object	Arbitrary JSON stored on the conversation.

bash

curl -X POST https://api.bolchoai.in/v1/conversations -H "Authorization: Bearer $BOLCHO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "agentId": "'$AGENT_ID'", "endUser": { "externalId": "user-42", "name": "Asha" } }'

Response

json

{ "id": "…", "agentId": "…", "channel": "api", "status": "open", "messageCount": 0, "costUsd": "0" }

GET/conversations chat:read

List conversations

List conversations with rollups (messages, cost, lead, sentiment).

Query parameters

agentId	uuid	Filter by assistant.
status	enum	open \| handoff \| resolved \| abandoned.
channel	enum	api \| widget \| whatsapp.
isLead	boolean	Only lead-captured conversations.
limit	number	Page size (default 20).
offset	number	Pagination offset.

bash

curl "https://api.bolchoai.in/v1/conversations?agentId=$AGENT_ID" -H "Authorization: Bearer $BOLCHO_API_KEY"

GET/conversations/analytics chat:read

Chat analytics

Rollup across conversations: totals, resolution/handoff/lead rates, cost, and sentiment.

Query parameters

agentId	uuid	Scope to one assistant.
channel	enum	api \| widget \| whatsapp.

bash

curl https://api.bolchoai.in/v1/conversations/analytics \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

GET/conversations/{id} chat:read

Get conversation

One conversation with its cost/token rollups and analysis fields.

Path parameters

id*

uuid

Conversation id.

bash

curl https://api.bolchoai.in/v1/conversations/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

GET/conversations/{id}/messages chat:read

List messages

The transcript — user/assistant/tool rows with per-message cost, citations and tool calls. Cursor-paginated by ordinal.

Path parameters

id*

uuid

Conversation id.

Query parameters

after	number	Return messages with ordinal greater than this (cursor).
limit	number	Max rows (default 50, max 200).

bash

curl https://api.bolchoai.in/v1/conversations/$ID/messages \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

Response

json

{ "data": [ { "ordinal": 1, "role": "user", "content": "…" }, { "ordinal": 2, "role": "assistant", "content": "…", "costUsd": "0.000252" } ], "nextCursor": null }

POST/conversations/{id}/messages chat:write

Send message

Send the user's message and get the assistant's reply (JSON, or SSE with Accept: text/event-stream). The assistant may call its tools mid-turn.

Path parameters

id*

uuid

Conversation id.

Body

content*	string	The user's message (max 8000 chars).
clientMessageId	string	Your unique id for this message — makes retries idempotent.
variableValues	object	Per-turn {{variable}} overrides for the prompt.
stream	boolean	Stream the reply as SSE (or send Accept: text/event-stream).

bash

curl -X POST https://api.bolchoai.in/v1/conversations/$CONV_ID/messages -H "Authorization: Bearer $BOLCHO_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f2f…" \
  -d '{ "content": "What is the price of a CBC test?", "clientMessageId": "m-1" }'

Response

json

{ "conversationId": "…", "message": { "id": "…", "role": "assistant", "content": "**CBC** costs ₹200 — no fasting needed.", "citations": [ … ] }, "usage": { "inputTokens": 2628, "outputTokens": 83, "costUsd": 0.00025 }, "status": "open" }

POST/conversations/{id}/resolve chat:write

Resolve conversation

Mark the conversation resolved (the customer's need was met).

Path parameters

id*

uuid

Conversation id.

bash

curl -X POST https://api.bolchoai.in/v1/conversations/$ID/resolve \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

POST/conversations/{id}/handoff chat:write

Flag for human

Move the conversation to handoff status for a human to take over.

Path parameters

id*

uuid

Conversation id.

bash

curl -X POST https://api.bolchoai.in/v1/conversations/$ID/handoff \
  -H "Authorization: Bearer $BOLCHO_API_KEY"

DELETE/conversations/{id} chat:write

Delete conversation

Delete the conversation and its messages.

Path parameters

id*

uuid

Conversation id.

bash

curl -X DELETE https://api.bolchoai.in/v1/conversations/$ID \
  -H "Authorization: Bearer $BOLCHO_API_KEY"