POST/api/global-chatbot/demo/poll

查询演示聊天会话中异步到达的新消息(例如人工客服已在主管理员后台接管对话时)——由小部件定期调用。

`POST /api/global-chatbot/demo/poll` 用于查询现有演示会话的新消息或状态变更。请求体包含 `session_id` 和 `visitor_id`,这两个值必须源自同一个公共演示会话。若缺少任一参数,服务器将返回 `400 PARAMS_REQUIRED`。 该路由无需用户登录,用于读取演示会话的当前状态。当响应未随上一条请求立即返回,或界面需要显示后续到达的消息时使用此功能。轮询并非发送消息的替代方案,也不会自行产生新的访客请求。 客户端必须在两次调用之间保持适当的间隔。过紧的死循环会增加负载并可能触发速率限制,却无法更快获得响应。若会话已终止、无效或无法找到,应停止轮询界面应提供重新开始的选项。已关闭的页面或隐藏的标签页不得遗留持续运行的后台请求。 `session_id` 和 `visitor_id` 并非其他会话的通用凭据。不得在访客间共享,也不得与消息一同发送至公共分析工具。演示环境与租户会话及生产收件箱数据保持隔离。 正确的测试流程为:启动演示会话,发送一条消息,随后使用相同的标识符调用轮询。此外,还需验证未包含 `visitor_id` 的请求。文档记录的失败场景测试只是错误验证,而非证实完整的生产对话已成功完成。

身份验证与安全

无需身份验证

幂等: 是

参数

session_id(body, string,必填)
visitor_id(body, string,必填)

请求示例

{"session_id":"<UUID>","visitor_id":"<UUID>"}

响应示例

{"ok":true,"data":{"messages":[]}}

错误代码

400 PARAMS_REQUIRED — session_id 和/或 visitor_id 缺失。

实时测试证明

成功(200,自 demo.chat 以来无新的异步消息,故为空列表)和失败场景(400)已实时验证。

← 演示聊天机器人和单点登录