获取访客基础数据

GET /visitor/data/get

访客聊天页完成身份校验后首先调用本接口。它返回当前访客资料、实时连接配置、前端功能开关和上传大小限制；后续分配客服、建立 WebSocket 连接、上传附件都依赖这些数据。

请求

无业务参数。在请求头携带当前访客 Token：

http

GET /visitor/data/get HTTP/1.1
Host: <部署域名>
Authorization: Bearer <visitor-token>
Accept: application/json

完整响应示例

以下 JSON 由当前控制器的实际返回字段整理。尖括号内是每个商户或访客运行时生成的值，不是接口返回的固定字面量；voice、sound、upload_file、upload_img、emoji 等开关由商户配置决定，没有配置时可能不出现。

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "visitor": {
      "nickname": "<访客昵称>",
      "avatar": "<访客头像 URL 或相对路径>",
      "uid": "<访客 UID>",
      "lang": "<语言代码>",
      "channel": "<服务端生成的访客实时频道>",
      "attributes": [
        {
          "key": "<属性机器名>",
          "label": "<属性展示名>",
          "type": "<属性类型>",
          "value": "<属性值>",
          "editable": false
        }
      ]
    },
    "setting": {
      "appname": "<系统名称>",
      "appkey": "<实时服务 appkey>",
      "ws_address": "<WebSocket 地址>",
      "upload_limits": {
        "image_max_bytes": 20971520,
        "file_max_bytes": 20971520,
        "video_max_bytes": 104857600,
        "voice_max_bytes": 20971520
      },
      "voice": "<语音开关值>",
      "sound": "<提示音开关值>",
      "upload_file": "<文件上传开关值>",
      "upload_img": "<图片上传开关值>",
      "emoji": "<表情开关值>",
      "session_invite_rating": "<评分邀请开关值>",
      "session_invite_resolved": "<解决状态邀请开关值>",
      "verified": true,
      "paid": 0
    }
  }
}

顶层字段

字段	类型	用途
`code`	number	业务状态码。`0` 表示成功，非 `0` 时不要继续初始化会话。
`msg`	string	状态说明；成功时通常为 `ok`。
`data`	object	本次初始化数据。

`data.visitor` 字段

字段	类型	用途
`nickname`	string	当前访客的展示昵称。
`avatar`	string	当前访客头像 URL 或站内相对路径。
`uid`	string	当前访客唯一标识。后续请求不能自行传递或替换该字段。
`lang`	string	当前访客语言代码，用于 FAQ、翻译和界面语言选择。
`channel`	string	当前访客的 WebSocket 订阅频道。必须直接使用返回值，不要由前端自行拼接。
`attributes`	array	访客扩展属性列表；未配置时为 `[]`。

`data.visitor.attributes[]` 字段

字段	类型	用途
`key`	string	属性机器名，例如 `member_level`。
`label`	string	展示名称，例如“会员等级”。
`type`	string	属性类型，例如 `text`、`image`。
`value`	string \| number \| boolean \| null	属性值。
`editable`	boolean	是否允许客服工作台编辑。图片属性固定为 `false`。

`data.setting` 字段

字段	类型	用途
`appname`	string	系统或商户展示名称。
`appkey`	string	实时服务连接使用的应用标识。
`ws_address`	string	WebSocket 服务地址。
`upload_limits`	object	各类上传文件的字节上限。上传前应使用此值校验。
`voice`	string	语音消息功能开关，通常为 `on` 或 `off`。
`sound`	string	消息提示音开关。
`upload_file`	string	普通文件上传功能开关。
`upload_img`	string	图片上传功能开关。
`emoji`	string	表情功能开关。
`session_invite_rating`	string	会话结束后是否邀请访客评分。
`session_invite_resolved`	string	会话结束后是否邀请访客反馈解决状态。
`verified`	boolean	当前商户是否通过服务端校验。
`paid`	number	已支付订单标识；无已支付订单时为 `0`。

`data.setting.upload_limits` 字段

字段	类型	用途
`image_max_bytes`	number	图片最大字节数。
`file_max_bytes`	number	普通文件最大字节数。
`video_max_bytes`	number	视频最大字节数。
`voice_max_bytes`	number	语音最大字节数。

后续操作

使用 data.visitor.channel 订阅访客实时频道。
使用 data.setting.ws_address 与 data.setting.appkey 建立实时连接。
调用“分配客服”接口取得当前会话客服。
上传前读取 data.setting.upload_limits，并同时遵守商户的上传功能开关。

获取访客基础数据 ​

请求 ​

完整响应示例 ​

顶层字段 ​

data.visitor 字段 ​

data.visitor.attributes[] 字段 ​

data.setting 字段 ​

data.setting.upload_limits 字段 ​

后续操作 ​