网站接入文档

1. 显示客服气泡

打开工作台的「网站与外观」，保存允许嵌入的网站地址，例如 https://shop.example。复制「嵌入代码」，放到网站页面的 </body> 前。普通访客的咨询前表单由工作台配置。

如果网站设置了内容安全策略，把你的 ChatNavo 域名加入网站的 script-src 和 frame-src。网站地址需匹配访客实际打开页面的协议、域名和端口。

2. 可选 · 自动识别已登录会员

在工作台「会员身份识别」生成专用密钥，存进商家网站后端的环境变量。复制「会员识别版代码」，把 data-identity-url 设为同源接口的路径，默认示例是 /chatnavo/identity。密钥只在网站后端使用。

气泡会请求商家网站的 GET /chatnavo/identity。在这个接口里，用网站现有的登录会话识别会员。未登录时返回 204 No Content。已登录时，从会话或数据库取得稳定的会员 ID，然后由网站后端发出下面这条 HTTPS 请求。代码里的域名替换成你的 ChatNavo 部署地址。

curl -X POST https://chat.example/api/identity/ticket \
  -H "Authorization: Bearer $CHATNAVO_IDENTITY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"12345","name":"小林"}'

userId 是必填的字符串，最多 128 个字符。name、phone 和 email 可选。请从已登录的账号读取这些值，忽略浏览器传来的用户 ID 或用户名。

ChatNavo 成功时返回 200 OK 和以下 JSON。商家接口把响应转交给浏览器，并为该接口的所有响应设置 Cache-Control: no-store。票据 60 秒内有效，仅可兑换一次。

{"ticket":"ChatNavo 返回的一次性票据","expiresIn":60}

接入失败时返回相应错误状态，气泡会提示重试。已识别的会员可跳过咨询前表单，客服会在「访客资料」看到「网站已登录」及会员 ID。访客收起再打开气泡时会重新检查身份。

3. 退出登录或切换会员

在商家网站完成退出或切换账号、且页面跳转之前，调用 await window.ChatNavo?.reset()，清除当前聊天窗口的登录状态。下一次打开气泡时，会按当前会员身份重新连接。

网站也可用自己的按钮调用 window.ChatNavo.open() 打开聊天。若使用自定义按钮，可在嵌入代码中添加 data-launcher="false" 隐藏默认气泡。