訊息回呼

業務 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。

訊息回呼 ​

配置與驗證 ​

回呼簽章 ​

文字訊息 ​

素材訊息 ​

動作訊息 ​