事件目录

负载结构

每个事件都是一个 JSON 对象：

{
  "id": "evt_01HKQN9…",
  "type": "conversation.created",
  "occurred_at": "2026-04-20T14:23:45.123Z",
  "account_id": "7c1d2c6e-…",
  "site_id": "0f3a…",
  "data": { … the resource, in the same shape the API returns it … }
}

id 是 X-RolChat-Event-Id 标头中的值，在重试之间保持不变。type 为 snake_case 格式的 <domain>.<noun>.<verb> 或 <domain>.<verb>。data 携带的资源与对应 GET 端点返回的结构相同，因此接收端可以按照 API 参考编写，永远不需要第二套架构。

事件系列

系列	示例	发出时机
`conversation.*`	`conversation.created`、`conversation.assigned`、`conversation.resolved`、`conversation.reopened`、`conversation.merged`	对话的状态或负责人发生变化
`message.*`	`message.created`、`message.delivered`、`message.read`、`message.failed`	发布了消息或其投递状态发生变化
`crm.*`	`crm.lead.created`、`crm.contact.created`、`crm.contact.updated`、`crm.contact.merged`、`crm.deal.stage_changed`、`crm.deal.won`	线索、联系人、公司或交易发生变化
`ticket.*`	`ticket.created`、`ticket.status_changed`、`ticket.assigned`、`ticket.sla_breached`	工单发生变化
`visitor.*`	`visitor.identified`、`visitor.cobrowse.requested`	访客被识别或请求协同浏览会话
`marketing.*`	`marketing.form.submitted`、`marketing.booking.created`、`marketing.campaign.sent`、`marketing.unsubscribed`	表单、预约、营销活动
`kb.*`	`kb.article.published`、`kb.article.unpublished`	知识库变更
`phone.*`	`phone.call.started`、`phone.call.ended`、`phone.call.recorded`、`phone.call.transcribed`、`phone.voicemail.received`	通话和语音信箱
`automation.*`	`automation.rule.executed`、`automation.rule.failed`	自动化规则运行
`privacy.*`	`privacy.consent.granted`、`privacy.consent.withdrawn`、`privacy.dsr.received`	同意和数据主体请求
`billing.*`	`billing.invoice.created`、`billing.trial_expiring`、`billing.subscription.changed`	订阅和发票
`auth.*`	`auth.api_key.created`、`auth.api_key.revoked`、`auth.account.swapped`	与安全相关的账户事件
`ai.*`	`ai.usage.recorded`	每次 AI 适配器调用，附带令牌计数

确切的列表会随产品不断增加；订阅界面会显示您的账户可以接收的每种类型，并允许按类型筛选。

Webhook 订阅属于某个插件。在 设置 → 插件 中打开该插件（或创建一个自定义插件）并添加端点：HTTPS URL、您需要的事件类型以及可选的 IP 允许列表。签名密钥只显示一次。该端点的投递、重试和死信会显示在插件的 Webhook 日志中。

插件页面上的 Plugin Protocol 介绍了插件如何在其清单中声明所需的事件。

顺序和投递

投递为至少一次。请按 id 去重。
同一资源的事件按顺序发出，但重试可能会打乱投递顺序。请使用 occurred_at 和资源的 updated_at，而不是到达时间。
持续失败的订阅会累积死信；单个端点超过 100 条时，RolChat 一侧会触发警报，并在插件日志中显示警告。