用户、客服分组与管理员会话列表

同 tag 用户和订单没有进入客服列表？复制客服端检查提示词，按“实际 Session 授权 → 用户分组 → 会话路由 → API 返回 → Widget 分页”检查。个人端和管理员端请使用对应端的模板，不要通过扩大权限补齐列表。

版本要求 · 2026-09-21

本页对应迁移 0056_customer_group_inheritance.sql、Widget 2.3.7、Loader 1.4.4。商户需使用匹配的服务端适配器并重新取得 Session；旧单会话 Token 不会自动扩大权限。其他环境需单独确认迁移与部署，生产业务验收仍由商户完成。

三种视角

身份	组件和凭证	可见范围
用户	Widget + 统一 Session 适配器	当前商户内本人已获授权的个人和订单会话，包括尚未首次打开的普通客服会话
客服、代理	同一 Widget + `wbs_`，`scope: groups`	授权分组下用户的个人咨询与订单客服会话
商户管理员	同一 Widget + `wbs_`，`scope: tenant`	当前商户授权范围内未进入删除流程的会话，不能跨商户

个人、客服和管理员复用同一个 Widget，不是把普通用户 Token 改成一个前端角色。列表、历史、附件和发送接口均在后端检查范围。新会话加入分组后会自动进入队列，不必重新枚举 conversation_id。

1. 设置用户分组（可选）

全部配置调用都在商户服务端完成，API Base 为 https://api.open4x.com。使用独立管理 Key，具备 conversation:supervise；签发工作台凭证还需要 conversation:read、conversation:write。不要把管理 Key 提供给浏览器或普通客服。

http

PUT /v1/conversations/customer-groups/site-a%3Auser-123
Authorization: Bearer <server supervision key>
Content-Type: application/json

{"group_tag":"sales-east"}

group_tag 为 1–100 位英文、数字、下划线或短横线。传 null 将用户明确设为未分组。用户改组后，其个人咨询和订单客服会话在后续请求中按新组授权，旧组不能继续读取或发送。用户未分组不影响本人访问；不对所有客服开放。Open4X 平台管理员不因此获得商户聊天权限。

2. 创建用户/订单会话并签发 Session

先按现有接口创建或 Upsert Conversation，订单使用 context_type: order、context_id: 订单编号，为用户建立 customer participant，并配置明确的客服接收人。商户后端必须核实订单属于当前用户，不能信任浏览器提交的 user_id、订单号或分组。

http

POST /v1/conversations/conv_example/widget-session
Authorization: Bearer <server supervision key>
Content-Type: application/json

{
  "external_user_id":"site-a:user-123",
  "user_name":"张先生",
  "participant_id":"participant_customer",
  "recipient_participant_ids":["participant_support"],
  "support_group":{},
  "ttl_seconds":1800
}

support_group: {} 或 {"group_tag":null}：明确加入客服队列，继承用户默认组。
support_group: {"group_tag":"vip"}：用户尚未设置分组时初始化为 vip，不再创建订单级覆盖。若用户已有其他分组，返回 409；改组必须调用 customer-groups，避免旧订单配置把用户转回旧组。
不传 support_group：保持原有路由，不自动加入分组队列。重复签发不会清除已经配置的路由。
用户和会话都没分组时，只能由商户管理员或已有明确会话授权的客服处理，不对所有客服开放。
只有 general_support、content_support、order_support 能加入分组。作者私聊和争议会话不能因此扩大权限。

以明确的用户归属为依据

设置用户分组时，会自动关联该用户已有、只有一个 customer 参与者的普通客服与订单客服会话；后续 Upsert 同样继承。作者私聊、争议会话、多 customer 会话不自动加入共享队列。旧数据中分组一致的记录迁移为用户分组，分组冲突则保持未分组，由商户管理员确认。metadata.tag 和前端标签不能授权。

已有会话可通过 PUT /v1/conversations/{id}/support-routing 配置：

json

{"external_user_id":"site-a:user-123","group_tag":null}

响应 data 返回 conversation_id、external_user_id、group_tag；group_tag 表示本次输入，不代表独立会话分组。external_user_id 必须匹配活动 customer 参与者，已有路由不可换绑其他用户。DELETE /v1/conversations/{id}/support-routing 移出队列，不删除历史；以后重新设置用户分组或 Upsert 符合条件的会话时会恢复继承。

SDK 提供 setCustomerGroup、setSupportRouting、removeSupportRouting。createWidgetSessionForContext 和 Session Handler 的 resolve 结果可带 support_group，无需额外自行拼接路由请求。

3. 用户看到全部个人会话

使用用户会话列表中的 /customer-session 签发列表 Token，并交给 Open4XSupportWidget。external_user_id 必须与上述 Session 一致。

单订单 Token 仍只允许进入该订单，不会自动升级。统一适配器为个人返回本人范围的列表凭证；商户不需要自行判断 Token 名称。已有有效 Widget 绑定继续使用；本人作为活动 customer 的普通客服和订单客服会话，即使从未打开，也会列出。首次打开且只有一个活动客服接收人时会自动建立绑定；没有或有多个候选客服时返回 409 widget_setup_required，由商户明确配置，不猜测接收人，不恢复已撤销的绑定。

列表显隐与授权独立：showConversationList: false 隐藏侧栏；conversationId 指定默认打开的 Open4X 会话 ID，仍需服务端校验本人权限。订单入口也可通过 /customer-session 的 conversation_id 传递默认打开位置。完整示例见统一 Session。

4. 客服分组工作台

商户后端验证客服登录和分组权限，再签发：

json

{
  "external_user_id":"staff:42",
  "origin":"https://widget.open4x.com",
  "scope":"groups",
  "group_tags":["sales-east","vip"],
  "mode":"agent",
  "manage":false,
  "ttl_seconds":900
}

调用 POST /v1/conversations/workbench-sessions。动态范围不要传 conversation_ids；原有固定 ID 模式继续兼容。响应包含 data.session_token、id、expires_at、expires_in。

新接入沿用统一 Loader，页面加载 https://widget.open4x.com/widget.js 后，将商户后端签发的短期凭证交给同一个组件：

Open4XWidget.init(session_token);

统一适配器的用法见一个 Widget 接入多端。已有 createOpen4XWorkbenchSessionHandler 的 authorize 回调仍从商户登录状态和员工权限返回 scope/group_tags；旧挂载接口仅用于兼容，不需要再安装独立工作台 UI。不要直接转发前端提交的分组或角色。

agent 模式第一次打开范围内会话时创建 support_agent 参与者，用于明确署名和回复；不会恢复已被移除的参与者。公开回复必须选择接收人，内部备注继续隔离。mode: read_only 只读，mode: notes 仅内部备注；manage: true 才允许已有的状态/分配操作。

5. 管理员

使用相同工作台和签发接口，将 scope 改为 tenant，不传 group_tags。商户后端必须确认当前用户是商户管理员，再签发该范围。

这是商户内会话查看和回复能力，不授予平台运营权限，也不授予底层 Key 或全局事件导出权限。独立的管理员接管/审计操作仍按会话管理的权限执行。

排序、未读与撤权

用户列表按本人最新可见公开消息时间降序，同时间按会话 ID 升序；无消息使用创建时间。返回 context_type/context_id，便于显示订单号。游标不透明，请原样传 next_cursor；新消息到来后从第一页刷新并按 ID 去重，不是不可变快照。
客服列表按最新公开消息时间降序，无消息使用创建时间。摘要不包含内部备注；未读按当前客服身份记录入站公开消息，不会因别的客服阅读而自动清零。
组范围每次请求重新检查；用户改组、移出队列、删除会话会影响下一次访问。已下载的数据无法从客户端追溯收回。
员工离职或分组权限变化时，商户后端应撤销其旧工作台 Session，并按新权限重新签发。接口为 DELETE /v1/conversations/workbench-sessions/{sessionId}。TTL 默认 900 秒，范围 60–3600 秒。
移除签发 Key 的 supervise/read/write 权限，停用 Key，或到期，也会使动态 Session 失效。

接入 AI 提示词

text

请按 Open4X conversation-groups 和 customer-conversation-list 文档接入。
先检查本项目现有登录、员工分组及订单归属，不新建另一套身份系统。
用户使用 customer-session 和 Widget 查看本人会话；客服使用服务端授权的
groups Workbench Session；管理员才使用 tenant Session。所有 API Key 留在后端。
创建订单会话时验证订单归属，以稳定 external_user_id 绑定 customer participant，
support_group={} 继承用户默认组；明确选定接收人。不得以 metadata 或前端 tag 授权。
补齐 CSRF、异常回退、空列表、未读、分页去重、撤权及跨租户负面测试。
先确认目标环境已部署 0056、Widget 2.3.7 和 Loader 1.4.4；未确认不宣称生产可用。

接口增补见分组 OpenAPI。本次不改变定价、限流或 SLA，不默认启用 AI。

用户、客服分组与管理员会话列表 ​

三种视角 ​

1. 设置用户分组（可选） ​

2. 创建用户/订单会话并签发 Session ​

3. 用户看到全部个人会话 ​

4. 客服分组工作台 ​

5. 管理员 ​

排序、未读与撤权 ​

接入 AI 提示词 ​