Chat & widget

Public Chatbot API

The browser-safe API that powers the embeddable chat widget. Authenticate with a publishable key (pk_live_…) in the x-voxa-public-key header — never put a secret API key in the browser.

Authentication

Send x-voxa-public-key: pk_live_… on every request. The key is locked to one assistant, an allow-list of domains (checked against the request Origin), and a per-key rate limit. Create keys via the Publishable keys API.

The send-message endpoint streams the same SSE event stream as the API-key chat (message.created → content.delta → message.completed → data: [DONE]). Send Accept: text/event-stream to stream.

GET/public/chatbot/config Publishable key

Get widget config

The widget's branding, greeting, starter questions, and lead-capture settings (assistant resolved from the key).

bash

curl https://api.bolchoai.in/v1/public/chatbot/config \
  -H "x-voxa-public-key: $BOLCHO_PUBLIC_KEY"

Response

json

{ "botName": "Acme Assistant", "color": "#10B981", "welcome": "Hi! How can I help?", "placeholder": "Type your message…", "suggestions": ["Book an appointment"], "leadCapture": true, "leadFields": ["name", "email"], "branding": "Powered by Bolcho AI" }

POST/public/chatbot/conversations Publishable key

Start a conversation

Open a widget conversation (channel = widget). Location/UTM context is captured server-side.

Body

clientRef	string	Your own thread id (max 200).
context	object	{ referrer?, landingUrl?, utm?, userAgent? }.

bash

curl -X POST https://api.bolchoai.in/v1/public/chatbot/conversations \
  -H "x-voxa-public-key: $BOLCHO_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "clientRef": "string",
  "context": {}
}'

Response

json

{ "id": "…", "agentId": "…", "status": "open" }

POST/public/chatbot/conversations/{id}/messages Publishable key

Send a message

Send the visitor's message and get the assistant's reply (JSON or SSE).

Path parameters

id*

uuid

Conversation id.

Body

content*	string	The visitor's message (max 8000).
clientMessageId	string	Your unique id for this message — makes retries idempotent.
stream	boolean	Stream the reply as SSE.

bash

curl -X POST https://api.bolchoai.in/v1/public/chatbot/conversations/$ID/messages \
  -H "x-voxa-public-key: $BOLCHO_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "string",
  "clientMessageId": "string",
  "stream": true
}'

Response

json

{ "conversationId": "…", "message": { "role": "assistant", "content": "…", "citations": [], "buttons": [] }, "usage": { "inputTokens": 812, "outputTokens": 96, "costUsd": 0.00021 }, "status": "open" }

POST/public/chatbot/lead Publishable key

Capture a lead

Save the visitor's contact details against the conversation.

Body

conversationId*	uuid	The conversation to attach the lead to.
name	string	Visitor name.
email	string	Visitor email.
phone	string	Visitor phone.
answers	object	Answers to any custom lead questions.

bash

curl -X POST https://api.bolchoai.in/v1/public/chatbot/lead \
  -H "x-voxa-public-key: $BOLCHO_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationId": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "email": "string",
  "phone": "string",
  "answers": {}
}'

Response

json

{ "ok": true, "conversationId": "…" }