API 参考

接收事件

标准事件类型与载荷

每次投递携带的统一信封，以及全部公开标准事件类型目录。按端点用 subscribed_events 订阅，或用 ["*"] 订阅全部公开事件；provider.raw_event 不会投递给客户。信封固定为 id / type / provider / account_id / occurred_at / data。 通话事件权限由工作区 is_beta 控制。内测工作区的 subscribed_events 为 *、空数组或省略时包含通话事件；具体事件列表仍仅匹配列出的事件。非内测工作区可使用通配订阅，但不会收到通话事件；明确订阅通话事件仍返回 403 beta_feature_not_enabled。每次投递、重试及死信重放都重新核验资格，查询失败不放行；普通 message.* 通话记录独立，不受该限制。

事件载荷

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:34:56Z",
  "data": {
    "account": { "provider_account_ref": "8600000000000" },
    "conversation": { "id": "8613912345678", "type": "user", "title": "Jordan Lee" },
    "sender": { "id": "8613912345678", "name": "Jordan Lee", "type": "user" },
    "message": {
      "id": "wamid.HBgM",
      "text": "Hi - is my order shipped yet?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:34:55Z"
    }
  }
}

标准事件类型

  • call.incoming

    call.incoming 是预留内测契约，目前不开放呼入。未来开放后，内测工作区可通过 subscribed_events 匹配订阅：逐项订阅、*、空数组或省略均可。

  • call.answered

    call.answered 表示本系统管理的通话已接通。内测工作区的 subscribed_events 包含 call.answered 或 *，或为空数组、省略时均可接收。

  • call.ended

    call.ended 表示本系统管理的通话已结束，包含 data.call.id、reason、duration_seconds。内测工作区的 subscribed_events 包含 call.ended 或 *，或为空数组、省略时均可接收。

  • post.comment.created

    通过识别及当前账号帖子归属校验后的 TikTok 评论通知。启用前须确认环境已开放通知且接收端已准备就绪。轮询默认关闭；设置 provider_data.enable_comment=true 后需启动或重连，在线修改需重连。start 成功不证明配置已生效；关闭不会撤回已排队事件。订阅 post.comment.created，或使用空订阅或 *；仅订阅不会开启轮询。通知尽力而为，可能延迟、重复、乱序或遗漏，不保证完整历史。按事件 id 去重。缺少 parent_comment_id 不能证明是可回复的一级评论；回复前须核验目标。

  • contact.updated

    WhatsApp 通讯录名称更新（不含 whatsapp-protocol）。仅更新 data.contact.address_book 中提供的字段：空字符串表示清空，省略保持原值，null 非法。不覆盖对方昵称或账号本人资料。contact.id 标识联系人资源，不一定是会话标识。

  • message.received

    账号观察到一条消息；以 data.message.direction 区分 inbound 与 outbound。

  • message.updated

    一条已投递的消息被编辑。

  • message.deleted

    一条消息被删除或撤回。

  • message.read

    已读回执——对方已读某条消息。

  • message.reaction

    某条消息被添加或移除了表态（reaction）。

  • message.delivered

    一条消息已送达对方设备。

  • conversation.updated

    会话级设置发生变化——静音 / 取消静音、归档、置顶或标记已读。

  • conversation.deleted

    一个会话被删除。

  • conversation.cleared

    一个会话的聊天记录被清空。

  • conversation.history

    WhatsApp 在启动或重连后同步了某个会话的近期历史消息。

  • group.updated

    群组元信息变化——名称、成员或设置。

  • group.join_request

    有人申请加入开启了入群审批的群。推送为尽力而为——请以轮询「列出入群申请」为准。

  • account.status.updated

    账号的运行时 / 连接状态发生变化。

  • account.profile.updated

    账号公开名称资料已同步；目前由 WhatsApp 名称事件触发。

  • account.started

    账号运行时已连接，可以收发消息。

  • account.history.synced

    一次 WhatsApp 历史同步批次已结束；data.summary 给出已投递的会话与消息数量。

  • account.auth.required

    账号需要（重新）认证——验证码、扫码或两步验证。

  • account.auth.succeeded

    账号授权成功。发送前查询账号，确认 runtime_status=running。

  • account.auth.failed

    一次认证尝试失败。

备注

  • 对于媒体消息，data.message.attachments[] 携带临时签名的 OSS url，以及 type、mimetype、size。
  • subscribed_events 必须填上面的精确事件名或 ["*"]；星号仅覆盖公开标准事件，不包含 provider.raw_event。创建或更新端点时，未知名称会被拒绝。
  • 并非每个 provider 都发出全部事件，部分载荷字段也有差异——按 provider 的差异见「Webhook 标准事件差异」矩阵。
  • message.read 与 message.delivered 携带精确的回执范围：data.message.ids 列出本次回执覆盖的全部消息，read_at / delivered_at 给出渠道上报的时间。
  • WhatsApp 实时 message.received 在渠道提供可回复的消息标识时，可能携带 data.message.reply_token；把它原样放入 POST /v1/messages 的 reply_to.reply_token。它用于回复当前消息，不是父消息 id；历史同步消息不包含该字段。