在线客服 SDK 接入
声邻 Voicelen 提供一段可直接嵌入网页的 JS 片段,在你的网站右下角展示悬浮气泡,点开即可与你的客服 / AI 机器人对话。访客侧接口在 /api/chat/web 下,不需要业务系统的 API Key,只用 channel_key + 一次性签发的 visitor_token 鉴权。
典型时序
- ① SDK 加载时读 data-key,调 POST /api/chat/web/init,拿 visitor_token 和渠道欢迎语
- ② 访客首次发消息,SDK 调 POST /api/chat/web/messages,后端建会话并返回 conv_uuid
- ③ SDK 拿到 conv_uuid 后订阅该会话频道,客服 / AI 后续每条回复通过实时推送到达页面
- ④ 断网重连时 SDK 可用 GET /api/chat/web/messages 补拉,避免丢消息
- ⑤ 访客手动关闭会话或长时间静默后由服务端超时关闭
visitor_token 说明
- init 时按 (channel_key, visitor_id) 签发,有效期 24 小时,过期后 SDK 静默重新 init
- 所有 /api/chat/web/* 接口均以 visitor_token 鉴权,不需要 Authorization: Bearer
- visitor_id 由 SDK 在浏览器本地生成并持久化,同一浏览器多次访问会命中同一访客记录
- 实时到达:SDK 使用 visitor_token 订阅会话专属推送频道,客服或 AI 的每一条回复都会主动推送到当前页面,无需轮询
/api/chat/web/initSDK 加载后首次调用,以 channel_key + visitor_id 换取 visitor_token 与渠道欢迎语。同一 visitor_id 多次调用幂等,后端只更新 user_info。
channel_keystring必填visitor_idstring必填user_infoobject可选三种场景任选其一:①首访(仅 welcome_text);②有 7 天内已结束会话(welcome_text + history_conv_uuid,SDK 拉该 conv 最近 20 条只读展示作为“上次对话记录”);③有活跃会话(conv_uuid,SDK 立即订阅并拉历史,不再展示 welcome_text)。
brand:渠道品牌视觉配置(可选,后台配置)。title 覆盖对话框顶栏标题;primary_color 为 #RRGGBB 主色,影响气泡按钮/发送按钮/客服气泡;bubble_position 为 right-bottom / left-bottom;bubble_offset_x/y 是距屏幕边缘的像素(0-200)。任一字段缺省时 SDK 走默认视觉。
/api/chat/web/messages发送一条访客消息。首条消息 conv_uuid 可留空,由服务端创建会话后在响应中返回;后续消息必须带上响应中的 conv_uuid。
visitor_tokenstring必填conv_uuidstring可选channel_msg_idstring可选content_typestring必填payloadobject必填/api/chat/web/messages访客端补拉某会话的历史消息(限定当前 visitor 名下)。keyset 分页:before 传上一次拿到的最小 message id,倒序返回。
tokenstring必填conv_uuidstring必填beforeint可选limitint可选/api/chat/web/close访客主动结束会话。已 closed 的会话再调返回 chat_conversation_closed。
visitor_tokenstring必填conv_uuidstring必填