客服端认证

客服端接口使用客服工作台 Session 认证。客服完成登录后，服务端将当前客服身份写入 Session；后续 /agent/* 请求通过 Cookie 或 Session ID 识别客服，不使用访客 Token。

客服端入口

客服工作台入口为：

GET /agent/

未登录时访问页面会跳转到客服登录页；未登录状态下请求 JSON 接口通常返回 code: -1，消息为“请登录”。

登录并建立 Session

先获取登录图形验证码，再调用：

POST /agent/login/check
Content-Type: application/x-www-form-urlencoded

username=<客服用户名>&password=<密码>&captcha=<验证码>&cid=<可选推送标识>

成功响应：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "token": "<当前客服 Session ID>",
    "redirect": "/agent/"
  }
}

返回字段	用途
data.token	当前登录 Session ID。可作为后续请求的 token 头或查询参数。
data.redirect	登录成功后的工作台跳转地址。

标准 Web 工作台应优先保存服务端 Cookie：

const response = await fetch('/agent/login/check', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
  },
  body: new URLSearchParams({ username, password, captcha })
})

使用 Session ID 调用接口

在不能使用 Cookie 的自定义客户端中，可以将登录响应的 token 放在请求头：

GET /agent/data/get
token: <当前客服 Session ID>

也支持查询参数形式：

GET /agent/data/get?token=<当前客服 Session ID>

服务端会把该值作为当前请求的 Session ID。token 是客服 Session，不是 Authorization: Bearer 访客 Token；两种身份不能互换。

不要把客服 Session 当作普通业务参数

不要将 token 写入 URL 日志、前端埋点、公开错误报告或分享链接。浏览器优先使用 HttpOnly Cookie，并在 HTTPS 环境启用 Secure Cookie。

登录后的初始化顺序

登录成功
   ↓
保存 Cookie / 临时保存 Session ID
   ↓
GET /agent/data/get
   ↓
读取 agent.agent_id、setting 与会话列表
   ↓
连接 WebSocket，订阅 agent-{agent_id} 与 global-{bid}

初始化接口返回的 agent、chatting、agent_groups、setting 和 extensions 是工作台首屏状态来源。不要在前端根据 URL 或本地缓存猜测 bid、客服角色和可用能力。

身份失效与权限

情况	服务端表现	客户端处理
Session 缺失或过期	JSON 接口返回 code: -1；页面请求跳转登录页。	停止写操作，重新登录并重新请求 /agent/data/get。
客服账号被禁用	写操作返回业务错误。	展示 msg，清理本地工作台状态并重新检查账号状态。
ticket_agent 角色访问在线接待接口	返回 403 或跳转工单入口。	仅展示其允许的工单范围，不要自动重试在线接待请求。
Session ID 与客服身份不匹配	操作失败或返回非法参数。	丢弃本地 Session，重新登录；不要替换请求中的客服 ID 继续提交。

服务端会根据 Session 判断当前客服所属商户和权限。业务请求不要自行补传商户密钥，也不要用访客 Token 访问客服接口。

退出与重连

退出时调用退出登录，并关闭当前客服 WebSocket、清理会话列表和未读状态。网络短暂断开时不要立即清除登录态；先重连并重新订阅，只有收到未登录响应时才回到登录流程。

实时连接细节见WebSocket 连接与订阅，工作台首屏数据见获取工作台初始化数据。