消息回调

业务 API 会话的角色消息以 POST 投递到当前空间已验证并启用的 MESSAGE 回调地址。缺少地址会投递失败，不使用其他空间的配置。

控制台互动测试使用平台收件箱，不会触发这个消息回调。 验证真实投递请用测试空间的开放 API；同步业务工具在控制台测试中仍可能真实执行。

配置与验证

在开放接口页设置消息回调及签名密钥。使用 HTTPS，不跟随重定向；内网地址不可作为公开回调。保存后执行验证，接收 OC-Event-Type: endpoint.verify 时验签并返回 2xx。修改地址后需要重新验证。

回调签名

请求头	说明
`OC-App-Key`	所属空间的 AppKey，用于选择对应回调密钥
`OC-Event-Id`	稳定事件 ID；消息回调为 `actionId`
`OC-Event-Type`	`chat.message`；地址验证为 `endpoint.verify`
`OC-Timestamp`	Unix 毫秒时间戳，每次尝试重新生成
`OC-Signature`	`v1=` 加 HMAC-SHA256 小写十六进制签名；轮换期可有逗号分隔的多个值
`Idempotency-Key`	与 `OC-Event-Id` 相同

使用该用途的回调密钥（不是 AppSecret），对以下四行 UTF-8 字符串签名；末尾没有换行：

text

OC-WEBHOOK-HMAC-SHA256
{OC-Event-Id}
{OC-Timestamp}
{原始请求体 SHA-256，小写十六进制}

先获取原始字节验签，再解析 JSON。时间戳建议允许正负 5 分钟；多个签名中任一匹配有效密钥即可。使用恒定时间比较。可直接使用Node.js 签名辅助程序中的 verifyWebhook。

文本消息

json

{
  "actionId": "123",
  "conversationId": "456",
  "messageId": "789",
  "type": "text",
  "text": "你好，今天过得怎么样？",
  "context": {
    "workspaceId": "1",
    "conversationId": "456",
    "personaId": "11",
    "personaUid": "anchor-001",
    "userId": "u-1001"
  }
}

personaUid 和 userId 是接入方标识，其余为平台标识。角色未绑定时 personaUid 可为 null。messageId 识别消息，actionId 用于投递幂等；它不是工具的 callId。

素材消息

启用并授权素材能力时，type 为 asset，带 asset 对象而非 text：

json

{
  "actionId": "124",
  "conversationId": "456",
  "messageId": "790",
  "type": "asset",
  "asset": {
    "assetId": "42",
    "kind": "image",
    "name": "图片",
    "url": "https://cdn.example.com/image.png",
    "caption": "给你看看"
  },
  "context": {
    "workspaceId": "1",
    "conversationId": "456",
    "personaId": "11",
    "personaUid": "anchor-001",
    "userId": "u-1001"
  }
}

示例 URL 不是可用资源。按 kind 显示素材；不要假设 URL 永久有效。这是角色输出能力，不代表用户输入已支持媒体。

动作消息

type: "action" 带 action 对象，见工具执行。EXECUTE 要执行并返回业务结果，NOTIFY 只展示已执行结果，不能再次执行。

响应与重试

消息	成功响应
文本、素材、`NOTIFY`	可靠接收后返回 HTTP 2xx，正文可为空
`EXECUTE`	HTTP 2xx + `{"status":"SUCCEEDED","data":{}}`；业务失败用 `FAILED`，未知用 `UNKNOWN`

工具结果 JSON 不使用平台 API 的 {code,message,data} 外层。

按 actionId 去重，重复投递返回已保存结果。业务动作也要按 action.callId 防止重复执行。
同一会话依消息顺序投递；重试期间后续消息等待。
4xx（408、429 除外）为明确拒绝，不重试。超时、5xx 等未知结果最多尝试 3 次，重试间隔 10 秒、30 秒；每次使用同一 actionId。
最终仍未知会停止自动重试，后续会话可继续。不能把未知当作未执行；普通未知消息不加入确认的对话上下文，未知动作会记录待核对提示。
EXECUTE 的 2xx 若没有合法业务状态，也会按未知处理；请返回完整 JSON，控制在 8000 UTF-8 字节内。消息回调请在 10 秒内响应，长任务目前没有另行完成回报接口。

目前未提供公开的人工核对／重新投递 API。

消息回调 ​

配置与验证 ​

回调签名 ​

文本消息 ​

素材消息 ​

动作消息 ​