主动发送聊天消息 API 指南

主动发送聊天消息 API 让外部系统或外部 Agent 服务按 EMP 标准向目标知办用户与指定知办数字员工的直聊会话投递一条结构化 Agent 消息。消息会进入会话历史，并按知办AI客户端的 EMP 渲染能力展示图表、表单、审批、文件、计划等组件。

适用场景

这是外部 Agent 向知办AI用户“发一条聊天内容”的默认接口。只要消息需要出现在聊天记录里，或需要携带图表、表单、审批卡片、文件、计划等 EMP 结构化内容，就应该调用本接口。

通常不需要再额外调用系统通知 API：主动聊天消息本身会更新会话预览、累加未读，并在目标会话不是当前打开会话时触发普通消息通知。只有“不想写入聊天记录，只想弹一个提醒并让用户点击进入会话”时，才单独使用系统通知 API。

调用权限

POST /api/external/v1/chat/messages

使用租户 API Key（ek_）调用，需要 tenant.chat.message.write scope。

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

知办AI会校验：

租户只从凭证解析，body 不能覆盖。
target.user_id 必须是当前租户 active 成员。
target.agent_id 必须是当前租户下的知办数字员工，并且对目标用户可见。
message.schema_version 必须是当前支持的 EMP schema 版本。
message.blocks 必须非空，且每个 block 都必须是已注册、stable 的 EMP 类型。

请求体

json

{
  "target": {
    "type": "agent_conversation",
    "user_id": "0b7f0d64-0a0c-4f8a-9d2d-9e14f4b20e22",
    "agent_id": "a1e718c7-0b93-4b64-9eb7-b05c2d9e731d"
  },
  "message": {
    "schema_version": "emp-1",
    "blocks": [
      {
        "type": "markdown",
        "text": "审批单已生成，请确认以下字段。"
      },
      {
        "type": "form",
        "title": "审批确认",
        "submit_label": "提交",
        "fields": [
          { "name": "approved", "label": "是否同意", "type": "select", "required": true }
        ]
      }
    ]
  },
  "third_message_id": "approval-1024"
}

字段说明：

字段	必填	说明
`target.type`	是	v1 固定为 `agent_conversation`，表示目标用户与指定数字员工的直聊会话。
`target.user_id`	是	目标知办用户账号 ID，值为知办平台稳定 UUID。
`target.agent_id`	是	知办数字员工 ID，值为知办平台稳定 UUID。
`message.schema_version`	是	当前固定为 `emp-1`。
`message.blocks`	是	标准 EMP block 数组，不能为空。
`third_message_id`	否	外部系统消息 ID，用于排查、审计和调用方侧去重记录；限制 128 字以内。v1 不做服务端幂等覆盖。

只发送 third_message_id。已删除的 external_id 请求字段会返回 HTTP 400，不再做兼容解析。

严格 EMP 规则

该接口不做内容兜底：

不接受 text / markdown 作为 blocks 之外的消息正文。
不把 blocks 压平成普通文本后投递。
不把未知 block 自动改写成 markdown。
不接受 draft / deprecated / 未注册的 block。
不接受外部系统塞任意客户端动作；交互 block 的 action 必须符合 EMP 标准。
图片、文件、音视频 block 必须使用客户端可访问、可鉴权或可过期的 URL / 文件引用，不能内联 base64。

不符合标准时，服务端直接返回 400 invalid_emp_block 或 400 unsupported_block_type，调用方应按 EMP 组件清单修正后重试。

成功响应

json

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

行业最佳实践与 EasyO 适配性

调研来源

Slack chat.postMessage：机器人按 channel 投递消息，支持结构化 blocks，并强调 channel 级限流。
Microsoft Teams proactive messages：主动消息发生在普通 activity handler 之外，但仍需要明确 conversation 上下文。
Matrix Client-Server API：客户端发送事件时用 transaction id 区分重试与新请求，实现幂等。

行业做法

主流协作产品都把“主动发送消息”建模成机器人/应用向明确会话投递消息，而不是任意系统通知；富内容用结构化 blocks/cards/events 表达；高频或可重试写入通常会引入调用方生成的去重标识。

EasyO 当前上下文

知办AI 已有 ZAP/EMP 富消息协议、EMP block registry、WuKong type=111 结构化 Agent final 消息，以及外部系统通知 API。缺口是：外部 Agent 无法主动向某个知办聊天框写入一条标准 EMP 聊天消息。

适配判断

adopt：明确目标会话、机器人身份、结构化 blocks、外部追踪 ID、独立 scope。

adapt：v1 只开放 user_id + agent_id 的数字员工直聊，暂不开放群聊投递；内容必须走 EMP registry 严格校验，不做 fallback；third_message_id 先用于审计和排查，不做服务端唯一幂等锁。

reject：不开放 WuKong 特权 REST；不接受任意 URL 跳转；不把系统通知接口扩展成聊天消息接口。

错误排查

HTTP	场景	建议
`400 invalid_emp_block`	block 缺字段、schema 不符合 EMP 标准	按 EMP 组件清单修正。
`400 unsupported_block_type`	block 未注册、非 stable 或 schema version 不支持	使用已上线 stable block。
`401`	API Key 缺失、格式错、过期或已撤销	重新创建或启用 API Key。
`403 scope_denied`	缺少 `tenant.chat.message.write`	给 API Key 增加主动消息写入能力。
`403 forbidden`	agent 不属于当前租户，或目标用户不可见	检查 `tenant_id / user_id / agent_id`。
`404 not_found`	目标用户不是当前租户 active 成员	用组织与人员 API 回查目标账号。
`502`	WuKong 推送链路暂不可用	稍后重试；若持续失败，带 `request_id` 联系运维排查。

主动发送聊天消息 API 指南 ​

适用场景 ​

调用权限 ​

请求体 ​

严格 EMP 规则 ​

成功响应 ​

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

调研来源 ​

行业做法 ​

EasyO 当前上下文 ​

适配判断 ​

错误排查 ​