系统通知 API 指南

通知 API 让租户外部业务系统主动向知办AI用户发送一条即时通知。通知不会写入聊天记录；桌面端收到后弹出标题和描述，用户点击通知进入对应知办数字员工对话。

适用场景

CRM 工单、审批、BI 告警等外部系统需要把“需要处理”的消息推给某个用户。
租户自建业务服务已完成一次判断，需要提醒目标知办用户回到知办AI中的指定知办数字员工对话继续处理。
通知只需要提醒用户回到指定数字员工对话，不应该污染聊天上下文。

如果外部 Agent 需要把结果、图表、表单、审批卡片等内容发到聊天框，通常只需要调用主动发送聊天消息 API。主动聊天消息会写入聊天记录、更新会话预览，并在非当前会话时按普通聊天消息触发未读和客户端通知；不要为了同一条聊天内容再额外调用系统通知，避免用户收到重复提醒。

不适合的场景：

群聊广播或全员公告。当前 API 只支持“目标知办用户 × 知办数字员工”的直聊通知。
跳转任意外部 URL。点击通知固定进入知办AI内的知办数字员工对话，避免外部系统把客户端导航带出边界。
需要向聊天记录写入图表、表单、审批卡片等结构化内容。请使用主动发送聊天消息 API。

调用权限

通知 API 使用租户 API Key（ek_）调用，需要 tenant.notification.write scope。

管理员 JWT 不可直接调用该接口。

调用时知办AI会校验：

凭证属于当前调用租户，租户只从 API Key 解析，不能由 body 覆盖。
agent_id 对应的知办数字员工属于当前调用租户，且对目标知办用户可见。
user_id 对应的目标知办用户账号是当前调用租户的有效成员。
目标知办用户与知办数字员工的直聊会话存在；不存在时自动创建，仅作为点击通知后的跳转目标，不写入聊天消息。

字段从哪里来

如果调用方已经接入自定义 Agent Runtime，通常不需要额外查询：

通知字段	来源	说明
`user_id`	ZAP `/zap/v1/instances`、`/zap/v1/sessions` 的用户上下文；或组织与人员 API `GET /org/members` 返回的 `account_id`	目标知办用户账号 ID，按 opaque string 使用。
`agent_id`	ZAP `/zap/v1/agents` 同步的知办数字员工配置，或 `/zap/v1/instances` 里的 `digital_employee_uuid`	知办数字员工 ID，值为知办平台稳定 UUID。
`third_notification_id`	外部系统自己的消息、工单或事件 ID	仅用于排查、审计关联和调用方侧幂等记录。

历史草稿里曾出现 account_uuid / agent_uuid / user_uuid / external_id。这些字段已在开发期删除，请统一使用 user_id / agent_id / third_notification_id；传入旧字段会返回 HTTP 400。

发送知办数字员工对话通知

POST /api/external/v1/notifications/agent-conversation

请求体：

json

{
  "user_id": "0b7f0d64-0a0c-4f8a-9d2d-9e14f4b20e22",
  "agent_id": "a1e718c7-0b93-4b64-9eb7-b05c2d9e731d",
  "title": "审批待处理",
  "description": "客户工单 #INC-1024 等待你确认处理方案",
  "third_notification_id": "crm-ticket-INC-1024"
}

字段说明：

字段	必填	说明
`user_id`	是	目标知办用户账号 ID，值为知办平台稳定 UUID；必须是当前租户有效成员。
`agent_id`	是	知办数字员工 ID，值为知办平台稳定 UUID；点击通知后进入该数字员工对话，且必须对目标知办用户可见。
`title`	是	桌面通知标题，建议 80 字以内。
`description`	是	桌面通知描述，服务端限制 1000 字以内；不会写入会话消息正文。
`third_notification_id`	否	外部系统消息 ID，用于排查和审计关联；当前不做幂等覆盖。

成功响应：

json

{
  "success": true,
  "code": 200,
  "message": "ok",
  "data": {
    "notification_id": "9ac84468-712f-4d71-b165-8b56da5351fe",
    "conversation_id": "b8970d57-4e62-47b5-a5c9-d944c3a9633f",
    "room_id": "d1b6508c-1a78-468a-86fb-062750d4a648"
  }
}

响应字段：

字段	说明
`notification_id`	通知事件 ID，用于排查和审计关联。
`conversation_id`	目标用户与该数字员工的直聊会话 ID。
`room_id`	会话房间稳定 ID。

示例

使用 API Key 发送通知

bash

curl -X POST "https://zhiban.creditease.corp/api/external/v1/notifications/agent-conversation" \
  -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0b7f0d64-0a0c-4f8a-9d2d-9e14f4b20e22",
    "agent_id": "a1e718c7-0b93-4b64-9eb7-b05c2d9e731d",
    "title": "审批待处理",
    "description": "客户工单 #INC-1024 等待你确认处理方案",
    "third_notification_id": "crm-ticket-INC-1024"
  }'

行业最佳实践与 EasyO 适配性

Microsoft Graph Teams activity notifications 支持按用户 / 聊天目标发送活动通知，并用 activity type 与 target 约束落点；EasyO 采用“目标知办用户账号 + 知办数字员工对话”的固定目标，避免任意跳转和跨租户误投。
Slack chat.postMessage 强调 per-channel 和 workspace 级限流；EasyO 本轮先保留服务端统一限流扩展点，接口契约不承诺无限吞吐。
Firebase Cloud Messaging 区分 notification/data payload，并用 click action/data 驱动客户端导航；EasyO 采用账号级事件推送通知 payload，点击动作固定映射到会话。

参考资料：Microsoft Graph Teams activity notifications、Teams activity feed best practices、Slack Web API rate limits、Firebase Cloud Messaging。

跳转到哪条对话

user_id + agent_id 对应目标知办用户与知办数字员工的一条直聊会话。调用通知接口时，知办AI会先准备或复用这条会话，并返回 conversation_id。客户端收到账号级通知事件后弹出系统通知；用户点击系统通知时进入该对话。

已接入系统需要同步字段切换，见 API 资源标识字段切换通知。

错误排查

HTTP	场景	建议
`401`	API Key 缺失、格式错、过期或已撤销	在租户后台重新创建或启用 API Key。
`403`	缺少 `tenant.notification.write`，或 `agent_id` 不属于当前调用租户 / 对目标知办用户不可见	给 API Key 增加通知写入 scope；确认数字员工属于当前租户且对目标用户可见。
`404`	目标知办用户不是当前调用租户的有效成员	用组织与人员 API 回查目标账号；确认调用方使用的是目标用户所在租户下的 API Key。
`502`	账号级通知推送链路暂不可用	稍后重试；若持续失败，带 `request_id` 联系运维排查。

系统通知 API 指南 ​

适用场景 ​

调用权限 ​

字段从哪里来 ​

发送知办数字员工对话通知 ​

示例 ​

使用 API Key 发送通知 ​

行业最佳实践与 EasyO 适配性 ​

跳转到哪条对话 ​

错误排查 ​