开发者文档

处理 API 渠道事件

理解 Callback Envelope、固定事件类型和公开回复载荷。

更新于 2026-07-24适合: 后端开发者

所有 Callback 使用统一 Envelope:

{
  "schemaVersion": 2,
  "id": "event-id",
  "sourceEventId": "source-event-id",
  "sequence": 12,
  "type": "message.created",
  "occurredAt": "2026-07-24T08:00:00Z",
  "tenantId": "tenant-id",
  "channelId": "channel-id",
  "conversationId": "conversation-id",
  "external": {
    "threadId": "thread-001",
    "customerId": "customer-001"
  },
  "source": { "type": "agent", "id": "agent-id", "name": "Agent" },
  "data": {}
}

固定事件

  • conversation.created
  • message.created
  • conversation.assigned
  • conversation.requeued
  • conversation.reopened
  • conversation.closed

message.created 只发送客服、主管、AI 或 Bot 的公开回复。客户通过 API 提交的消息不会回声,内部备注也不会发送。

使用事件 id 去重,使用 sequence 判断同一会话内相对顺序。不要假设不同会话之间严格有序。

相关指南