订单会话状态批量查询

已发布

两个批量查询接口已于 2026-09-14 发布到 API 正式环境。配套 SDK 源码需同步升级；也可直接使用 HTTP 请求，无需升级 SDK。

用于订单列表显示“暂无会话”“查看会话”和未读徽标，不加载消息正文。

服务端调用

POST https://api.open4x.com/v1/conversations/order-statuses

认证使用服务端 API Key，要求 conversation:read。继承 Key 的来源、限流及额度策略；一次批量请求按一次 API 请求处理，并不代表免费或免配额。

{
  "external_participant_id": "agent-123",
  "external_order_ids": ["ORDER-001", "ORDER-002"]
}

{
  "data": [
    {"external_order_id":"ORDER-001","has_conversation":true,"has_messages":true,"has_unread":true,"unread_count":3,"conversation_count":2},
    {"external_order_id":"ORDER-002","has_conversation":false,"has_messages":false,"has_unread":false,"unread_count":0,"conversation_count":0}
  ]
}

最多 100 个编号，每个编号及查看者标识最多 200 字符，不接受空白、首尾空格和控制字符。重复编号去重，按首次出现顺序返回。查询不创建会话，也不写已读状态。创建了会话但没有消息时，has_conversation=true、has_messages=false。

身份与订单关联

• 创建会话时设置 context_type=order、context_id=订单编号，不按 metadata 猜测订单归属。
• 将有权限的代理商加入对应会话，使用稳定的 external_participant_id，角色为 customer、creator 或 support_agent。
• 商户后端从登录态解析查看者身份，并检查本次订单列表的业务授权；不得直接信任浏览器提交的查看者 ID。此接口是商户服务端的委托查询能力，不是浏览器认证接口。
• 仅统计当前租户、活动参与者的会话，排除已进入删除流程的会话。仅分配负责人而没有添加参与者，不会获得此接口的可见性。
• 多个用户与订单之间的归属仍由商户系统维护；关系变更时必须同步撤销 Open4X 参与者权限。
• 无权限与不存在均返回空状态。一个订单下多条可见会话合并统计；不可见的另一方会话不参与统计。
• 未读按查看者独立计算，排除本人发送的消息、内部备注及不在收件人范围的消息；只计算公开消息，包括客服视角。查询不会自动已读。

SDK 与其他业务

const result = await client.getOrderStatuses(authenticatedParticipantId, orderIds);
const statuses = new Map(result.data.map(item => [item.external_order_id, item]));

通用接口：POST /v1/conversations/context-statuses。

{"external_participant_id":"agent-123","context_type":"resource","context_ids":["RESOURCE-1"]}

返回结构相同，但编号字段为 context_id。SDK：getContextStatuses(viewerId, contextType, contextIds)。

建议只查询当前页订单，在切页、重新聚焦和收到消息事件后刷新；轮询应退避，遵循 Key 配额。接口失败时显示“状态暂不可用”，不要把失败显示成“没有消息”。商户响应同样应禁止共享缓存，避免跨用户复用。

独立 OpenAPI 规范 提供两个端点的完整请求和响应结构。

AI 接入提示词

请为当前订单列表接入 Open4X 批量会话状态接口。先确认目标环境已发布此能力。
在服务端从登录态解析 external_participant_id，验证订单归属，使用服务端 Secret 中的 API Key 调用。
每批最多100个订单，使用 context_type=order/context_id 建立会话关联，代理商需成为活动参与者。
按 external_order_id 显示会话入口和未读数。失败、加载中和无会话分别展示，不能把失败转换为0条未读。
不可把 API Key 放进浏览器，不可允许前端任意指定查看者，不可在列表查询时提交已读。
测试跨租户、跨代理商、内部备注隔离、多个会话、重复订单号及权限撤销。