跳转到内容

在线客服 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 的每一条回复都会主动推送到当前页面,无需轮询
POST/api/chat/web/init

SDK 加载后首次调用,以 channel_key + visitor_id 换取 visitor_token 与渠道欢迎语。同一 visitor_id 多次调用幂等,后端只更新 user_info。

请求体
channel_keystring必填
工作台配置渠道时生成的字符串
visitor_idstring必填
访客在浏览器端的持久标识,SDK 自动生成并存 localStorage
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 走默认视觉。

POST/api/chat/web/messages

发送一条访客消息。首条消息 conv_uuid 可留空,由服务端创建会话后在响应中返回;后续消息必须带上响应中的 conv_uuid。

请求体
visitor_tokenstring必填
init 返回的 token
conv_uuidstring可选
首条留空,后续必填(值来自上一次响应)
channel_msg_idstring可选
客户端幂等 ID,重传去重用;不传时后端自动生成
content_typestring必填
text / image / file
payloadobject必填
text 用 {text},image/file 用 {url,name?,size?}
GET/api/chat/web/messages

访客端补拉某会话的历史消息(限定当前 visitor 名下)。keyset 分页:before 传上一次拿到的最小 message id,倒序返回。

查询参数
tokenstring必填
init 返回的 visitor_token
conv_uuidstring必填
会话 uuid
beforeint可选
上一次拿到的最小 message id,首次不传
limitint可选
每页数量,默认 50
POST/api/chat/web/close

访客主动结束会话。已 closed 的会话再调返回 chat_conversation_closed。

请求体
visitor_tokenstring必填
init 返回的 token
conv_uuidstring必填
要关闭的会话 uuid

鄂ICP备2022005956号-2