对话

在自己的 App 或客服系统里和 AI 对话，支持流式返回，以及会话的转人工、结束和评价。

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
}

不传 conversation_id 时新建会话，响应里返回它，后续消息带上。
user 由你的服务器直接告诉我们（API Key 调用方是可信的），带了才能查订单。
默认回复语言：传 user.language（如 de、zh-CN、pt-BR）就用它；否则传 user.ip，我们按所在地判断；都不传用后台的默认语言。顾客在对话里要求换语言后，以顾客的要求为准。
stream: false 时返回 {"conversation_id", "message", "status", "products"}；message 为 null 表示会话在人工接待中，消息已转给人工。
stream: true 时返回 SSE，事件见下表。

事件 `type`	内容
`user_message`	已保存的用户消息
`delta`	回答的一段文字 `text`，按顺序拼接
`products`	AI 查到的商品卡片
`language`	顾客要求换了回复语言，`language` 是新的语种代码
`status`	会话状态变化（比如转人工）
`replace`	用 `text` 整体替换已收到的回答（出错时换成兜底话术）
`queued_for_human`	会话在人工接待中，没有 AI 回答
`done`	最终保存的消息和会话状态
`error`	出错

其他接口

方法	路径	说明
GET	`/v1/conversations`	会话列表，`?status=&end_user_id=`
GET	`/v1/conversations/{id}/messages`	会话和全部消息
POST	`/v1/conversations/{id}/messages`	你的客服系统以人工身份回复：`{"content", "agent_name"}`，会话随即进入人工状态
POST	`/v1/conversations/{id}/status`	客服一方操作：`{"status": "ai"}` 交还给 AI，`{"status": "closed"}` 结束会话
POST	`/v1/conversations/{id}/close`	顾客在你的 App 里结束会话；已经结束的也返回成功
POST	`/v1/conversations/{id}/rating`	会话结束后顾客评价：`{"rating": "good" \| "bad", "comment": "可选，最多 500 字"}`，可以改

会话状态：ai（AI 回答）、pending_human（等待人工）、human（人工接待中）、closed（已结束）。

会话里还有：closed_by 谁结束的（customer 顾客、agent 客服、ai 顾客表示没有其他问题后 AI 结束），rating / rating_comment / rated_at 顾客评价。

结束会话：网页窗口头部有「结束会话」按钮（二次确认）；微信小程序里顾客发「结束」也会结束；「机器人设置」里打开「AI 自动结束会话」时，顾客明确表示没有其他问题，AI 道别后结束会话。结束后网页窗口请顾客评价满意 / 不满意并可留言，微信里请顾客回复 1 或 2；之后顾客再发消息是新的会话。

转人工后的分配：「机器人设置」里选择分配方式——分给手上会话最少的客服（默认）、轮流分配，或客服自己接。自动分配只分给选了「在线」并且后台页面开着的客服，每人有同时接待上限（「团队」页设置）；分到的客服超过设定时间（默认 2 分钟）没回复就改派。会话里的 assigned_member_id 是分到的客服，assigned_at 是分配时间，handoff_at 是转人工时间。人都满了时顾客排队，网页窗口显示前面还有几位。

营业时间和留言：「机器人设置」里打开营业时间后，营业时间外顾客转人工不会排队，网页窗口弹出留言表单（称呼、邮箱或手机、问题），微信和开放 API 的对话由 AI 请顾客留言；营业时间内没有客服在线也一样。留言生成工单，客服回复时，原会话还没结束就发进会话，顾客留了邮箱也会以店铺名义发邮件。只推给你的系统（转人工方式选「推送到我的系统」）时不看营业时间。

这篇文档有帮助吗？

最后更新: 2026年10月31日