Conversations

Chat with AI inside your own app or customer service system, with streaming responses, plus handoff to a human agent, session closing, and ratings.

POST /v1/chat

{
  "message": "有没有 400 美元以内的潜水表？",
  "conversation_id": null,
  "user": {"id": "u_123", "name": "李四", "email": "li@example.com", "ip": "85.214.132.117", "language": null},
  "stream": false
}

If you don't pass conversation_id, a new conversation is created; it's returned in the response, and you include it in subsequent messages.
user is sent to us directly by your server (the API Key caller is trusted) — order lookup only works when it's included.
Default reply language: if you pass user.language (e.g. de, zh-CN, pt-BR), that's used; otherwise pass user.ip and we infer it from the location; if neither is passed, the dashboard's default language is used. Once the customer asks to switch languages in the conversation, the customer's request takes precedence.
With stream: false, the response is {"conversation_id", "message", "status", "products"}; a message of null means the conversation is being handled by a human agent and the message has been handed off.
With stream: true, the response is SSE; see the table below for events.

Event `type`	Content
`user_message`	The saved user message
`delta`	A segment of the answer's text `text`; concatenate in order
`products`	Product cards the AI found
`language`	The customer asked to switch the reply language; `language` is the new language code
`status`	Conversation status change (e.g. handed off to a human)
`replace`	Replace the answer received so far with `text` (on error, swapped for fallback wording)
`queued_for_human`	The conversation is being handled by a human agent; there's no AI answer
`done`	The final saved message and conversation status
`error`	An error occurred

Other endpoints

Method	Path	Description
GET	`/v1/conversations`	Conversation list, `?status=&end_user_id=`
GET	`/v1/conversations/{id}/messages`	The conversation and all its messages
POST	`/v1/conversations/{id}/messages`	Your customer service system replies as a human agent: `{"content", "agent_name"}`; the conversation then enters the human-handled state
POST	`/v1/conversations/{id}/status`	Agent-side action: `{"status": "ai"}` hands back to AI, `{"status": "closed"}` ends the conversation
POST	`/v1/conversations/{id}/close`	The customer ends the conversation in your app; returns success even if it has already ended
POST	`/v1/conversations/{id}/rating`	Customer rating after the conversation ends: `{"rating": "good" \| "bad", "comment": "可选，最多 500 字"}`; can be changed

Conversation statuses: ai (AI answering), pending_human (waiting for a human), human (being handled by a human), closed (ended).

A conversation also includes: closed_by, who ended it (customer the customer, agent the agent, ai the AI ended it after the customer indicated there were no other questions), and rating / rating_comment / rated_at for the customer's rating.

Ending a conversation: The web widget header has an "End conversation" button (with a confirmation step); in the WeChat Mini Program, the customer sending "end" also ends the conversation; when "AI automatically ends conversations" is enabled in "Bot settings" and the customer clearly indicates there are no other questions, the AI says goodbye and ends the conversation. After it ends, the web widget asks the customer to rate it as satisfied / unsatisfied and optionally leave a comment; in WeChat, the customer is asked to reply 1 or 2. Any messages the customer sends afterwards start a new conversation.

Assignment after handoff: In "Bot settings", choose an assignment method — assign to the agent with the fewest active conversations (default), round-robin, or let agents pick up conversations themselves. Automatic assignment only goes to agents who have selected "Online" and have the dashboard page open, and each agent has a limit on simultaneous conversations (set on the "Team" page); if the assigned agent doesn't reply within a set time (2 minutes by default), the conversation is reassigned. In the conversation, assigned_member_id is the assigned agent, assigned_at is the assignment time, and handoff_at is the handoff time. When everyone is at capacity, customers queue, and the web widget shows how many people are ahead of them.

Business hours and messages: Once business hours are enabled in "Bot settings", handoff requests outside business hours aren't queued — the web widget shows a message form (name, email or phone, question), and in WeChat and open API conversations the AI asks the customer to leave a message; the same applies during business hours when no agent is online. Messages create a ticket; when an agent replies, the reply goes into the original conversation if it hasn't ended yet, and if the customer left an email, it's also sent by email in the store's name. Business hours don't apply when you only push to your own system (handoff method set to "Push to my system").

Was this page helpful?

Last updated: October 31, 2026