访客端接口概览

访客端接口用于自建 Web / H5 咨询页。访客身份由业务服务端签发的 Web 访客 Token 确认；浏览器负责会话初始化、消息交互、上传和实时同步。

接入顺序

业务服务端签发访客 Token
          ↓
打开 GET /visitor?token=...&group_id=...
          ↓
GET /visitor/data/get
          ↓
POST /visitor/chatting/find
          ↓
FAQ、消息历史、WebSocket 订阅
          ↓
发送消息、已读、输入状态、上传与会话反馈

接口分组

能力	常用接口	用途
身份与初始化	/visitor	建立访客身份。
身份与初始化	/visitor/data/get	读取访客资料、实时配置和上传限制。
会话与客服	/visitor/chatting/find	按分组为当前访客分配或复用客服。
消息	/visitor/message/get	加载历史消息。
消息	/visitor/message/send	发送文本或上传后的媒体消息。
阅读与输入	/visitor/message/readed	同步消息已读状态。
阅读与输入	/visitor/message/updateLastReadTime	更新最后阅读时间。
阅读与输入	/visitor/message/typing	同步对方输入状态。
访客资料	/visitor/data/language	同步访客语言。
访客资料	/visitor/data/attributes	同步访客扩展属性。
访客资料	/visitor/data/contexts	同步商品、订单等咨询上下文。
会话反馈	/visitor/session/rate	提交会话评分。
会话反馈	/visitor/session/resolve	提交问题解决状态。
文件上传	/visitor/upload/img	上传图片、视频或语音。
文件上传	/visitor/upload/file	上传文件后再发送消息。

认证与请求格式

除上传文件的兼容场景外，访客业务请求统一携带：

Authorization: Bearer <visitor-token>

Token 已包含访客身份，业务请求不能重复传递 bid、uid、name、nickname、avatar 或 profile_mode。Web 访客 Token 的格式、签发和安全边界见访客入口与凭证。

实时与一致性

HTTP 是业务数据的最终来源；WebSocket 仅用于下行同步。客户端收到 message.created 时按 mid 去重，重连后重新订阅并按消息历史的 mid 游标补拉遗漏消息。

首次实现建议优先完成：初始化、客服分配、消息历史、发送消息、实时消息、已读与断线补拉。其他资料同步、评分和解决状态可在主链路稳定后接入。

不要混用 SDK 接口

本组为 Web 访客页使用的 /visitor/* 接口。原生和跨端访客 SDK 使用独立的 /sdk/visitor/* 路由，具体见访客 SDK。