访客页入口与认证

GET /visitor

第三方服务端生成访客 Token 后，将访客浏览器跳转或嵌入到此地址。成功后页面加载的全部 /visitor/* 请求都必须携带同一 Token。

text

GET /visitor?token=<visitor-token>&group_id=0

参数	必填	说明
`token`	是	服务端签发的访客 JWT。它包含商户和访客身份，不能由前端伪造。
`group_id`	否	客服分组 ID，默认 `0`。
`tc`	否	`#RRGGBB` 格式的主题色。
`mini`	否	小窗展示标记。
`channel`	否	渠道标识；最长 32 个字符。

调用访客接口

除上传文件的受限兼容场景外，所有 /visitor/* 请求都在 HTTP 头传递 Token：

http

Authorization: Bearer <visitor-token>

Token 模式下，查询参数或请求体中不得再传 bid、uid、name、nickname、avatar、profile_mode。这些字段只能来自服务端验证后的 Token。

当 Token 中 uid 为空时，必须先访问一次 /visitor 入口，让服务端创建并签发绑定 UID 的新 Token；随后才能调用业务接口。

Web 访客 Token 内容

Web 访客页使用与原生 SDK 不同的 Web Token 契约。它是 HS256 三段式 JWT，Payload 必须且只能包含以下字段：

json

{
  "bid": "<商户 ID>",
  "uid": "<访客 ID，可为空>",
  "name": "<访客昵称，可为空>",
  "avatar": "<头像 URL，可为空>",
  "profile_mode": "fill"
}

字段	规则
`bid`	必填，当前商户 ID。
`uid`	可为空；为空时首次访问 `/visitor` 由服务端补齐身份。
`name`	可为空，最长 128 个字符。
`avatar`	可为空，最长 1024 个字符。
`profile_mode`	`fill` 或 `overwrite`；决定访客资料的合并方式。

商户后端使用该商户的 apiKey 对 Header 与 Payload 进行 HMAC-SHA256 签名。不要加入 exp、role、任意自定义字段，也不要把 API Key 放到浏览器。

服务端签发示例

项目内可由服务端直接调用 WebVisitorToken::create()：

php

use app\service\WebVisitorToken;

$token = WebVisitorToken::create(
    $apiKey,              // 仅服务端保存
    $bid,
    $currentUserId,
    $currentUserName,
    $currentUserAvatar,
    'fill'
);

$url = 'https://<客服系统域名>/visitor?token=' . rawurlencode($token) . '&group_id=0';

fill 适合只补全空资料；需要以业务系统资料覆盖访客已有名称、头像时使用 overwrite。商户被禁用、过期或没有配置 API Key 时，即使签名正确，服务端仍会拒绝 Token。

浏览器侧安全要求

Token 仅通过 HTTPS 传输；不要写入页面源码、URL 分享记录、浏览器日志或第三方统计参数。
访客端请求始终使用 Authorization: Bearer <visitor-token>，上传文件的受限兼容场景除外。
Token 校验失败后停止重试，回到业务服务端重新生成入口地址；不要让浏览器自行签名或修改 Payload。
Web 访客 Token 与原生/跨端 SDK Token字段不同，不能互换使用。

访客页入口与认证 ​

GET /visitor ​

调用访客接口 ​

Web 访客 Token 内容 ​