Webhook 载荷示例

messenger.inbound_message.received — Messenger 入站文本

使用 messengerInboundMessage.id 关联重复的客户消息；保留文本空格。

{
  "id": "evt_0123456789abcdef01234567",
  "type": "messenger.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:00.000Z",
  "messengerInboundMessage": {
    "id": "1308528868252065793",
    "metaMessageId": "m_EXAMPLE_IN_001",
    "from": "100800000000000",
    "to": "422500000000000",
    "type": "text",
    "text": {
      "body": "  Hello  "
    },
    "sendTime": "2026-10-20T02:00:00.000Z",
    "createTime": "2026-10-20T02:00:00.100Z"
  }
}

messenger.inbound_message.updated — Messenger 入站文本编辑

同一条保存的消息现在包含最新文本和累计编辑详情。

{
  "id": "evt_cdef0123456789abcdef0123",
  "type": "messenger.inbound_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:01:00.000Z",
  "messengerInboundMessage": {
    "id": "1308528868252065793",
    "metaMessageId": "m_EXAMPLE_IN_001",
    "from": "100800000000000",
    "to": "422500000000000",
    "type": "text",
    "text": {
      "body": "  Hello, corrected  "
    },
    "sendTime": "2026-10-20T02:00:00.000Z",
    "createTime": "2026-10-20T02:00:00.100Z",
    "editCount": 2,
    "editTime": "2026-10-20T02:01:00.000Z"
  }
}

messenger.message.updated — Messenger 出站已读快照

使用消息 ID 关联快照；未知的中间送达时间将被省略。

{
  "id": "evt_89abcdef0123456789abcdef",
  "type": "messenger.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:03.000Z",
  "messengerMessage": {
    "id": "1308528868252065792",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "from": "422500000000000",
    "to": "100800000000000",
    "type": "text",
    "text": {
      "body": "How can I help you?"
    },
    "status": "read",
    "createTime": "2026-10-20T02:00:00.000Z",
    "updateTime": "2026-10-20T02:00:03.000Z",
    "readTime": "2026-10-20T02:00:03.000Z"
  }
}

messenger.message_reaction.updated — Messenger 消息表情回应

目标 Meta 消息无需在 YCloud 本地拥有消息记录。

{
  "id": "evt_abcdef0123456789abcdef01",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:04.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "react",
    "reaction": "love",
    "emoji": "❤️"
  }
}

messenger.message_reaction.updated — Messenger 消息表情回应已撤回

撤回操作可以省略回应名称和表情符号。

{
  "id": "evt_bcdef0123456789abcdef012",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:05.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "unreact"
  }
}

whatsapp.echo_message.created — 出站文本 Echo

存储来自 whatsappMessage.text.body 的文本。id 和 wamid 用于关联后续的状态事件。

{
  "id": "evt_example_echo_text",
  "type": "whatsapp.echo_message.created",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "type": "text",
    "text": {
      "body": "Hello! How can I help you?"
    },
    "status": "sent",
    "createTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

whatsapp.echo_message.created — 出站图片 Echo

消息内容因类型而异。请将媒体 ID 视为提供商引用标识，而非公开下载 URL。

{
  "id": "evt_example_echo_image",
  "type": "whatsapp.echo_message.created",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:00.000Z",
  "whatsappMessage": {
    "id": "IMAGE_MESSAGE_ID",
    "wamid": "wamid.IMAGE_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "type": "image",
    "image": {
      "id": "MEDIA_ID",
      "mime_type": "image/jpeg"
    },
    "status": "sent",
    "createTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

whatsapp.echo_message.updated — Echo 消息已送达

通过 id 或 wamid 与创建事件进行关联。更新事件会省略消息内容和类型。

{
  "id": "evt_example_echo_delivered",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "delivered",
    "updateTime": "2026-09-09T02:00:01.000Z",
    "deliverTime": "2026-09-09T02:00:01.000Z"
  }
}

whatsapp.echo_message.updated — Echo 消息已读

通过 id 或 wamid 与创建事件进行关联。更新事件会省略消息内容和类型。

{
  "id": "evt_example_echo_read",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "read",
    "updateTime": "2026-09-09T02:00:02.000Z",
    "readTime": "2026-09-09T02:00:02.000Z"
  }
}

whatsapp.echo_message.updated — 已读后到达的发送状态

优先级较低的源状态可能会在已读后到达。记录该事件时，请勿降级您当前的消息状态。

{
  "id": "evt_example_echo_sent",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "sent",
    "updateTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

whatsapp.echo_message.updated — 失败的 Echo 消息

这是一条单独的失败消息，并非从已读状态转变而来。失败更新会在可用时包含源错误详情。

{
  "id": "evt_example_echo_failed",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "FAILED_MESSAGE_ID",
    "wamid": "wamid.FAILED_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "failed",
    "errorCode": "131000",
    "errorMessage": "Provider failure",
    "updateTime": "2026-09-09T02:00:03.000Z"
  }
}

whatsapp.meta_business_agent.handover.updated — Agent 将控制权交接给您的应用程序

APP_CONTROL_TAKEN 报告的是控制权转交，而非 Inbox 员工分配或自定义转交消息投递。在本示例中，actor 是上一任所有者应用的 ID。

{
  "id": "evt_example_agent_handover",
  "type": "whatsapp.meta_business_agent.handover.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:04.000Z",
  "whatsappMetaBusinessAgent": {
    "agentId": "00000000-0000-4000-8000-000000000001",
    "metaAgentId": "META_AGENT_ID",
    "phoneNumberId": "PHONE_NUMBER_ID",
    "wabaId": "WABA_ID",
    "consumerPhoneNumber": "+12025550124",
    "controlState": "APP_CONTROL_TAKEN",
    "actor": "PREVIOUS_OWNER_APP_ID",
    "reason": "customer_request",
    "timestamp": 1788919204000
  }
}

whatsapp.business_account.deleted — WhatsApp 商业账户已删除事件

读取 whatsappBusinessAccount.id 以识别账户。若存在，removedReason、removedInitiatedBy 和 removedTime 会描述移除详情。请保留未知的 reason 和 initiator 值。

{
  "id": "evt_business_account_deleted_123",
  "type": "whatsapp.business_account.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "removedReason": "ACCOUNT_DISCONNECTED",
    "removedInitiatedBy": "USER",
    "removedTime": "2026-05-26T12:00:00.000Z"
  }
}

whatsapp.phone_number.quality_updated — WhatsApp 电话号码质量已更新事件

从 whatsappPhoneNumber 读取 qualityRating 和 qualityUpdateEvent。messagingLimit 描述电话号码层级；whatsappBusinessManagerMessagingLimit 描述所属业务资产组合的限制。

{
  "id": "evt_phone_number_quality_updated_123",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "TIER_2K",
    "qualityUpdateEvent": "ONBOARDING"
  }
}

contact.attributes_changed — 联系人属性已更改事件

联系人属性更改时的示例载荷

{
  "id": "evt_1234567890",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "remark_name": {
        "oldValue": "Standard customer",
        "newValue": "Priority customer"
      },
      "email": {
        "oldValue": "john.doe@example.com",
        "newValue": "johnny.doe@example.com"
      },
      "tags": {
        "oldValue": [
          "premium",
          "newsletter"
        ],
        "newValue": [
          "premium",
          "newsletter",
          "vip"
        ],
        "extra": [
          {
            "action": "ADDED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

contact.created — 联系人已创建事件

创建新联系人时的示例载荷

{
  "id": "evt_2345678901",
  "type": "contact.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactCreated": {
    "id": "1824266594102064128",
    "remarkName": "Priority customer",
    "nickName": "John Doe",
    "realName": "John Smith",
    "phoneNumber": "+16315551111",
    "countryCode": "US",
    "countryName": "United States",
    "email": "john.doe@example.com",
    "sourceType": "api",
    "sourceId": "import_batch_123",
    "sourceUrl": "https://example.com/signup",
    "lastSeen": "2024-01-01T11:59:00.000Z",
    "lastConnectedNumber": "+16315552222",
    "ownerEmail": "owner@example.com",
    "tags": [
      "premium",
      "newsletter"
    ],
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "blocked": false,
    "customAttributes": {
      "attr1": "value1",
      "attr2": "value2",
      "attr3": 123
    }
  }
}

contact.deleted — 联系人已删除事件

删除联系人时的示例载荷

{
  "id": "evt_3456789012",
  "type": "contact.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactDeleted": {
    "id": "1824266594102064128",
    "remarkName": "Former customer",
    "nickName": "John Doe",
    "phoneNumber": "+16315551111",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

contact.note.created — 联系人备注已创建事件

{
  "id": "evt_1234567890abcdef12345678",
  "type": "contact.note.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactNote": {
    "id": "6a3de646e18f344f743aaa4d",
    "contactId": "1824266594102064128",
    "username": "alice_01",
    "phoneNumber": "+16315551111",
    "content": "Customer prefers follow-up in the morning.",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

contact.note.updated — 联系人备注已更新事件

{
  "id": "evt_2234567890abcdef12345678",
  "type": "contact.note.updated",
  "apiVersion": "v2",
  "createTime": "2024-01-02T12:00:00.000Z",
  "contactNote": {
    "id": "6a3de646e18f344f743aaa4d",
    "contactId": "1824266594102064128",
    "username": "alice_01",
    "phoneNumber": "+16315551111",
    "content": "Customer now prefers afternoon follow-up.",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-02T12:00:00.000Z"
  }
}

contact.note.deleted — 联系人备注已删除事件

仅在单独删除备注时触发，联系人级联删除时不触发。

{
  "id": "evt_3234567890abcdef12345678",
  "type": "contact.note.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-03T12:00:00.000Z",
  "contactNote": {
    "id": "6a3de646e18f344f743aaa4d",
    "contactId": "1824266594102064128",
    "username": "alice_01",
    "phoneNumber": "+16315551111",
    "content": "Customer now prefers afternoon follow-up.",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-02T12:00:00.000Z"
  }
}

contact.unsubscribe.created — 客户取消订阅事件

客户取消订阅时的示例载荷

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

contact.unsubscribe.deleted — 客户恢复订阅

客户恢复订阅时的示例载荷

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

whatsapp.phone_number.business_username_updated — WhatsApp 电话号码商业用户名已更新事件

WhatsApp 电话号码商业用户名生效时的示例载荷

{
  "id": "evt_business_username_updated_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

whatsapp.phone_number.business_username_updated — WhatsApp 电话号码商业用户名已预留事件

WhatsApp 电话号码具有预留商业用户名请求时的示例载荷

{
  "id": "evt_business_username_pending_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:30:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "reserved",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:30:00.000Z"
  }
}

whatsapp.template.correct_category_detection — Utility Direct Send 类别检测事件

Meta 在 Utility Direct Send 消息中检测到营销内容。请通过 Webhook 端点 API 订阅此事件。

{
  "id": "evt_direct_send_category_123",
  "type": "whatsapp.template.correct_category_detection",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "auto_generated_sample",
    "language": "en_US",
    "category": "MARKETING",
    "previousCategory": "UTILITY"
  }
}

whatsapp.business_account.updated — Utility Direct Send 限制事件

因多次滥用类别，Meta 对 Utility Direct Send 实施了为期 7 天的限制。

{
  "id": "evt_direct_send_restriction_123",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "violationType": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
        "expiration": "2026-09-24T08:00:00.000Z"
      }
    ]
  }
}

whatsapp.template.reviewed — WhatsApp 模板归档事件

WhatsApp 模板归档时的示例负载

{
  "id": "evt_template_archived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "statusUpdateEvent": "ARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

whatsapp.template.reviewed — WhatsApp 模板取消归档事件

WhatsApp 模板取消归档时的示例负载。该模板状态是 Meta 返回的当前状态，并不代表重新进行了审批审核。

{
  "id": "evt_template_unarchived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "statusUpdateEvent": "UNARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

whatsapp.call.connect — WhatsApp 通话接通事件

WhatsApp 通话接通时的示例负载

{
  "id": "evt_call_connect_123",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "callingConnect": {
    "id": "6757b723960b25543b9ecc66",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEF",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "dialTime": 1733826430000,
    "sdpType": "offer",
    "sdp": "v=0\r\no=- 1732169627243 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS af3b01e3-eb42-4244-812e-db903c062ae7\r\na=ice-lite\r\nm=audio 3480 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 31.13.87.130\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:785588535 1 udp 2122260223 31.13.87.130 3480 typ host generation 0 network-cost 50\r\na=candidate:1906600321 1 udp 2122262783 2a03:2880:f217:d0:face:b00c:0:699c 3480 typ host generation 0 network-cost 50\r\na=ice-ufrag:CvRXRnInnWhQzLIE\r\na=ice-pwd:HGXUGAFI8wK6seuVknBT2Q==\r\na=fingerprint:sha-256 FB:56:A1:C5:37:35:6C:5C:1B:05:23:B0:DD:BB:2E:C9:5F:E4:70:61:7B:D9:1D:09:84:76:46:23:12:38:B7:01\r\na=setup:actpass\r\na=mid:audio\r\na=sendrecv\r\na=msid:af3b01e3-eb42-4244-812e-db903c062ae7 WhatsAppTrack1\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=maxptime:20\r\na=ptime:20\r\na=ssrc:659928310 cname:WhatsAppAudioStream1\r\n"
  }
}

whatsapp.call.terminate — WhatsApp 通话终止事件

WhatsApp 通话终止时的示例负载

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEFENjB",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

whatsapp.call.status.updated — WhatsApp 通话状态更新事件

WhatsApp 通话状态更新时的示例负载

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "status": "RINGING",
    "recipientPhone": "+6281361905133"
  }
}

whatsapp.call.recording.updated — WhatsApp 通话录音更新事件

源自 API 的通话录音可用时的示例负载

{
  "id": "evt_call_recording_01JZ8K4V7H3P6Q9R2T5W8X1Y4Z",
  "type": "whatsapp.call.recording.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:00:00.000Z",
  "callingRecording": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0c2e4b05c2d8f1a3b47",
    "status": "AVAILABLE"
  }
}

whatsapp.call.transcription.updated — WhatsApp 通话转录更新事件

源自 API 的通话转录永久失败时的示例负载

{
  "id": "evt_call_transcription_01JZ8K5A9C4D7E0F3G6H9J2K5M",
  "type": "whatsapp.call.transcription.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:01:00.000Z",
  "callingTranscription": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0d9e4b05c2d8f1a3b48",
    "status": "FAILED",
    "error": {
      "code": "CALLING_TRANSCRIPTION_PROCESSING_FAILED",
      "retryable": false
    }
  }
}

whatsapp.group.lifecycle_update — WhatsApp 群组生命周期更新事件

创建 WhatsApp 群组时的示例负载

{
  "id": "evt_group_lifecycle_123",
  "type": "whatsapp.group.lifecycle_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "displayPhoneNumber": "16315551111",
    "phoneNumberId": "1234567890123456",
    "field": "group_lifecycle_update",
    "type": "group_create",
    "requestId": "REQ_1",
    "status": "created",
    "groupId": "120363345678901234@g.us",
    "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK",
    "subject": "New Purchase Inquiry",
    "description": "Group for purchase inquiries.",
    "joinApprovalMode": "auto_approve",
    "webhookTime": "2026-05-13T00:00:00.000Z",
    "dedupeKey": "123456789012345|REQ_1|group_lifecycle_update|group_create|created"
  }
}

whatsapp.group.participants_update — WhatsApp 群组成员更新事件

添加 WhatsApp 群组成员时的示例负载

{
  "id": "evt_group_participants_123",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "120363345678901234@g.us",
    "waId": "16315551111",
    "recipientUserId": "US.1234",
    "parentRecipientUserId": "US.parent123",
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    },
    "addedParticipants": [
      {
        "input": "US.1234",
        "waId": "16315551111",
        "recipientUserId": "US.1234",
        "parentRecipientUserId": "US.parent123",
        "customerProfile": {
          "name": "John Doe",
          "username": "john_doe"
        }
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

whatsapp.group.settings_update — WhatsApp 群组设置更新事件

WhatsApp 群组设置更新时的示例负载

{
  "id": "evt_group_settings_123",
  "type": "whatsapp.group.settings_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_settings_update",
    "type": "group_settings_update",
    "requestId": "REQ_2",
    "status": "updated",
    "groupId": "120363345678901234@g.us",
    "subject": "Updated Purchase Inquiry",
    "description": "Updated group description.",
    "settings": [
      {
        "name": "group_subject",
        "text": "Updated Purchase Inquiry",
        "updateSuccessful": true
      },
      {
        "name": "group_description",
        "text": "Updated group description.",
        "updateSuccessful": true
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

whatsapp.group.status_update — WhatsApp 群组状态更新事件

WhatsApp 群组封禁状态发生变化时的示例负载

{
  "id": "evt_group_status_123",
  "type": "whatsapp.group.status_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_status_update",
    "type": "group_suspend",
    "status": "suspended",
    "groupId": "120363345678901234@g.us",
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

whatsapp.smb.message.created — SMB 消息已创建

从 whatsappMessage 中读取出站消息。消息类型决定了其内容对象；此示例包含文本。

{
  "id": "evt_example_smb_created",
  "type": "whatsapp.smb.message.created",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z"
  }
}

whatsapp.smb.message.echoes — WhatsApp Business App 文本消息

此事件用于同步从 WhatsApp Business 应用或支持的配套设备发送的消息。可从 whatsappMessage 读取其内容。

{
  "id": "evt_example_smb_echoes",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "username": "example_customer"
    }
  }
}

whatsapp.smb.history — 入站历史消息

入站历史消息使用 whatsappInboundMessage。phase 和 progress 用于报告历史数据块的同步情况。

{
  "id": "evt_example_smb_history_inbound",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappInboundMessage": {
    "id": "INBOUND_MESSAGE_ID",
    "wamid": "wamid.INBOUND_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222",
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "What time can I collect my order?"
    },
    "customerProfile": {
      "name": "Example customer"
    },
    "sendTime": "2026-10-08T12:00:00.000Z"
  }
}

whatsapp.smb.history — 出站历史消息

出站历史消息使用 whatsappMessage。请勿将其作为入站消息进行路由。

{
  "id": "evt_example_smb_history_outbound",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "phase": 1,
  "progress": 60,
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z"
  }
}

whatsapp.smb.history — 历史记录同步进度

仅包含元数据的历史数据块仅报告 phase 和 progress，不包含任何一种消息对象。请勿将此结构视为 message-created 或 message-echoes 负载。

{
  "id": "evt_example_smb_history_progress",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "phase": 1,
  "progress": 73
}

email.delivery.updated

{
  "id": "evt_1234567890",
  "type": "email.delivery.updated",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "emailDelivery": {
    "emailId": "<string>",
    "recipientAddress": "tom@example.com",
    "status": "failed",
    "errorCode": 402,
    "errorMessage": "Unsubscribes",
    "externalId": "<string>",
    "bizType": "email",
    "verificationId": "VERIFICATION-ID"
  }
}

sms.message.updated

{
  "id": "evt_1234567890",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "sms": {
    "id": "<string>",
    "to": "+16315551111",
    "text": "Your verification code is 123456.",
    "senderId": "Brand",
    "regionCode": "US",
    "totalSegments": 1,
    "totalPrice": 0.0085,
    "currency": "USD",
    "status": "sent",
    "errorCode": "<string>",
    "createTime": "2022-03-01T12:00:00.000Z",
    "updateTime": "2022-03-01T12:00:00.000Z",
    "externalId": "<string>",
    "callbackUrl": "https://httpbin.org/anything?tag=api-sms",
    "bizType": "sms",
    "verificationId": "VERIFICATION-ID"
  }
}

sms.inbound.received

{
  "id": "evt_1234567890",
  "type": "sms.inbound.received",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "smsInbound": {
    "id": "<string>",
    "from": "+16315551111",
    "to": "<string>",
    "text": "<string>",
    "sendTime": "2022-06-01T12:00:00.000Z"
  }
}

voice.message.updated

{
  "id": "evt_1234567890",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "voice": {
    "id": "<string>",
    "to": "+16315551111",
    "verificationCode": "123456",
    "language": "en",
    "regionCode": "US",
    "totalSegments": 1,
    "totalPrice": 0.05,
    "currency": "USD",
    "status": "sent",
    "errorCode": "<string>",
    "createTime": "2022-03-01T12:00:00.000Z",
    "updateTime": "2022-03-01T12:00:00.000Z",
    "externalId": "<string>",
    "callbackUrl": "https://httpbin.org/anything?tag=api-voice",
    "bizType": "voice",
    "verificationId": "VERIFICATION-ID"
  }
}

whatsapp.business_account.reviewed

{
  "id": "evt_1234567890",
  "type": "whatsapp.business_account.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "<string>",
    "name": "<string>",
    "currency": "<string>",
    "messageTemplateNamespace": "<string>",
    "accountReviewStatus": "PENDING",
    "businessVerificationStatus": "expired",
    "country": "<string>",
    "ownershipType": "<string>",
    "paymentMethodAttached": false,
    "primaryFundingId": "<string>",
    "purchaseOrderNumber": "<string>",
    "timezoneId": "1",
    "decision": "APPROVED",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "SCHEDULE_FOR_DISABLE",
    "banDate": "December 9, 2022",
    "violationType": "SCAM",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2022-06-01T12:00:00.000Z"
      }
    ],
    "maxPhoneNumbersPerBusiness": 20,
    "maxPhoneNumbersPerWaba": 25,
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ],
    "primaryBusinessLocation": "US",
    "removedReason": "ACCOUNT_DISCONNECTED",
    "removedInitiatedBy": "USER",
    "removedTime": "2026-05-19T12:00:00.000Z"
  }
}

whatsapp.inbound_message.received

{
  "id": "evt_1234567890",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "<string>",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+16315551111",
    "fromUserId": "US.1234",
    "fromParentUserId": "US.ENT.1234",
    "customerProfile": {
      "name": "John",
      "username": "john_doe"
    },
    "to": "+16315551111",
    "sendTime": "2022-06-01T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "<string>"
    },
    "image": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>",
      "metadata": {
        "key": {}
      },
      "mime_type": "<string>",
      "sha256": "<string>"
    },
    "video": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>",
      "metadata": {
        "key": {}
      },
      "mime_type": "<string>",
      "sha256": "<string>"
    },
    "audio": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>",
      "metadata": {
        "key": {}
      },
      "mime_type": "<string>",
      "sha256": "<string>"
    },
    "document": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>",
      "metadata": {
        "key": {}
      },
      "mime_type": "<string>",
      "sha256": "<string>"
    },
    "sticker": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>",
      "metadata": {
        "key": {}
      },
      "mime_type": "<string>",
      "sha256": "<string>"
    },
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "<string>",
        "title": "<string>"
      },
      "list_reply": {
        "id": "<string>",
        "title": "<string>",
        "description": "<string>"
      },
      "nfm_reply": {
        "name": "flow",
        "response_json": "{\"flow_token\":\"unused\",\"screen_0_firstName_0\":\"王\",\"screen_1_TextInput_1\":\"123\",\"screen_1_TextInput_0\":\"11\",\"screen_0_lastName_1\":\"TESTNAME\"}",
        "body": "Sent"
      },
      "call_permission_reply": {
        "response": "accept",
        "expiration_timestamp": 1672531200,
        "is_permanent": false
      }
    },
    "location": {
      "latitude": 0.0,
      "longitude": 0.0,
      "address": "<string>",
      "name": "<string>",
      "url": "<string>"
    },
    "button": {
      "payload": "<string>",
      "text": "<string>"
    },
    "contacts": [
      {
        "addresses": [
          {
            "street": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zip": "<string>",
            "country": "<string>",
            "country_code": "<string>",
            "type": "WORK"
          }
        ],
        "birthday": "2022-09-27",
        "emails": [
          {
            "email": "<string>",
            "type": "WORK"
          }
        ],
        "name": {
          "formatted_name": "<string>",
          "first_name": "<string>",
          "last_name": "<string>",
          "middle_name": "<string>",
          "suffix": "<string>",
          "prefix": "<string>"
        },
        "org": {
          "company": "<string>",
          "department": "<string>",
          "title": "<string>"
        },
        "phones": [
          {
            "phone": "<string>",
            "type": "<string>",
            "wa_id": "<string>"
          }
        ],
        "urls": [
          {
            "url": "<string>",
            "type": "<string>"
          }
        ],
        "vcard": "<string>",
        "origin": "contact_request"
      }
    ],
    "reaction": {
      "message_id": "wamid.BgNODYxN...",
      "emoji": "<string>"
    },
    "order": {
      "catalog_id": "the-catalog_id",
      "product_items": [
        {
          "product_retailer_id": "<string>",
          "quantity": 0,
          "item_price": 0.0,
          "currency": "USD"
        }
      ],
      "text": "<string>"
    },
    "system": {
      "body": "<string>",
      "wa_id": "<string>",
      "user_id": "US.13491208655302741919",
      "parent_user_id": "US.ENT.11815799212886844831",
      "type": "<string>",
      "user": "<string>",
      "new_wa_id": "<string>"
    },
    "errors": [
      {
        "code": 131051,
        "title": "Message type unknown",
        "message": "Message type unknown",
        "error_data": {}
      }
    ],
    "context": {
      "forwarded": false,
      "frequently_forwarded": false,
      "from": "<string>",
      "id": "wamid.BgNODYxN...",
      "referred_product": {
        "catalog_id": "<string>",
        "product_retailer_id": "<string>"
      }
    },
    "referral": {
      "source_url": "<string>",
      "source_type": "<string>",
      "source_id": "<string>",
      "headline": "<string>",
      "body": "<string>",
      "media_type": "<string>",
      "image_url": "<string>",
      "video_url": "<string>",
      "thumbnail_url": "<string>",
      "ctwa_clid": "<string>"
    },
    "groupId": "120363345678901234@g.us"
  }
}

whatsapp.message.updated

{
  "id": "evt_1234567890",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappMessage": {
    "id": "<string>",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+16315551111",
    "to": "+16315551111",
    "recipient": "US.1234",
    "recipientUserId": "US.1234",
    "toUserId": "US.1234",
    "parentRecipientUserId": "US.parent123",
    "toParentUserId": "US.parent123",
    "customerProfile": {
      "name": "John",
      "username": "john_doe"
    },
    "conversation": {
      "id": "<string>",
      "type": "FREE_ENTRY",
      "originType": "referral_conversion",
      "expireTime": "2022-06-01T12:00:00.000Z"
    },
    "type": "template",
    "template": {
      "name": "sample_whatsapp_template",
      "language": {
        "code": "en_US",
        "policy": "deterministic"
      },
      "components": [
        {
          "type": "header",
          "sub_type": "quick_reply",
          "index": 0,
          "parameters": [
            {
              "type": "text",
              "text": "<string>",
              "payload": "<string>",
              "coupon_code": "<string>",
              "image": {
                "id": "<string>",
                "link": "<string>",
                "caption": "<string>",
                "filename": "<string>"
              },
              "gif": {
                "id": "<string>",
                "link": "<string>",
                "caption": "<string>",
                "filename": "<string>"
              },
              "video": {
                "id": "<string>",
                "link": "<string>",
                "caption": "<string>",
                "filename": "<string>"
              },
              "document": {
                "id": "<string>",
                "link": "<string>",
                "caption": "<string>",
                "filename": "<string>"
              },
              "limited_time_offer": {
                "expiration_time_ms": "1698562800000"
              },
              "action": {
                "thumbnail_product_retailer_id": "2lc20305pt",
                "sections": [
                  {}
                ],
                "flow_token": "<string>",
                "flow_action_data": {
                  "key": {}
                },
                "order_details": {
                  "currency": "<string>",
                  "reference_id": "<string>",
                  "type": "<string>",
                  "payment_settings": []
                }
              },
              "order_status": {
                "reference_id": "<string>",
                "order": {
                  "type": "<string>",
                  "catalog_id": "<string>",
                  "items": [],
                  "description": "<string>"
                }
              },
              "location": {
                "latitude": 0.0,
                "longitude": 0.0,
                "name": "<string>",
                "address": "<string>"
              }
            }
          ],
          "cards": [
            {
              "card_index": 0,
              "components": [
                {
                  "type": "header",
                  "sub_type": "quick_reply",
                  "index": 0,
                  "parameters": []
                }
              ]
            }
          ]
        }
      ]
    },
    "text": {
      "body": "<string>",
      "preview_url": false
    },
    "image": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>"
    },
    "video": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>"
    },
    "audio": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>"
    },
    "document": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>"
    },
    "sticker": {
      "id": "<string>",
      "link": "<string>",
      "caption": "<string>",
      "filename": "<string>"
    },
    "location": {
      "latitude": 0.0,
      "longitude": 0.0,
      "name": "<string>",
      "address": "<string>"
    },
    "interactive": {
      "type": "button",
      "action": {
        "buttons": [
          {
            "type": "reply",
            "reply": {
              "title": "<string>",
              "id": "<string>"
            }
          }
        ],
        "button": "<string>",
        "catalog_id": "<string>",
        "product_retailer_id": "<string>",
        "sections": [
          {
            "title": "<string>",
            "rows": [
              {
                "id": "<string>",
                "title": "<string>",
                "description": "<string>"
              }
            ],
            "product_items": [
              {
                "product_retailer_id": "<string>"
              }
            ]
          }
        ],
        "name": "cta_url",
        "parameters": {
          "display_text": "See Docs",
          "url": "https://developers.facebook.com/docs/whatsapp",
          "thumbnail_product_retailer_id": "<string>",
          "flow_message_version": "<string>",
          "flow_token": "<string>",
          "flow_id": "<string>",
          "flow_name": "<string>",
          "flow_cta": "Open flow!",
          "flow_action": "navigate",
          "flow_action_payload": {
            "screen": "<string>",
            "data": {
              "key": {}
            }
          },
          "reference_id": "<string>",
          "type": "<string>",
          "beneficiaries": [
            {
              "name": "<string>",
              "address_line1": "<string>",
              "address_line2": "<string>",
              "city": "<string>",
              "state": "<string>",
              "country": "<string>",
              "postal_code": "<string>"
            }
          ],
          "currency": "<string>",
          "total_amount": {
            "offset": 100,
            "value": 1234,
            "description": "<string>",
            "discount_program_name": "<string>"
          },
          "order": {
            "status": "pending",
            "type": "<string>",
            "catalog_id": "<string>",
            "items": [
              {
                "retailer_id": "<string>",
                "name": "<string>",
                "image": {},
                "amount": {},
                "sale_amount": {},
                "quantity": 0,
                "country_of_origin": "<string>",
                "importer_name": "<string>",
                "importer_address": "<string>"
              }
            ],
            "subtotal": {
              "offset": 100,
              "value": 1234,
              "description": "<string>",
              "discount_program_name": "<string>"
            },
            "tax": {
              "offset": 100,
              "value": 1234,
              "description": "<string>",
              "discount_program_name": "<string>"
            },
            "shipping": {
              "offset": 100,
              "value": 1234,
              "description": "<string>",
              "discount_program_name": "<string>"
            },
            "discount": {
              "offset": 100,
              "value": 1234,
              "description": "<string>",
              "discount_program_name": "<string>"
            },
            "expiration": {
              "timestamp": "1727438564",
              "description": "<string>"
            },
            "description": "<string>"
          },
          "payment_settings": [
            {
              "type": "payment_gateway",
              "payment_gateway": {
                "type": "billdesk",
                "configuration_name": "<string>",
                "billdesk": {},
                "payu": {},
                "razorpay": {},
                "zaakpay": {}
              }
            }
          ]
        }
      },
      "body": {
        "text": "<string>"
      },
      "header": {
        "type": "text",
        "text": "<string>",
        "image": {
          "id": "<string>",
          "link": "<string>",
          "caption": "<string>",
          "filename": "<string>"
        },
        "video": {
          "id": "<string>",
          "link": "<string>",
          "caption": "<string>",
          "filename": "<string>"
        },
        "document": {
          "id": "<string>",
          "link": "<string>",
          "caption": "<string>",
          "filename": "<string>"
        }
      },
      "footer": {
        "text": "<string>"
      }
    },
    "contacts": [
      {
        "addresses": [
          {
            "street": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zip": "<string>",
            "country": "<string>",
            "country_code": "<string>",
            "type": "WORK"
          }
        ],
        "birthday": "2022-09-27",
        "emails": [
          {
            "email": "<string>",
            "type": "WORK"
          }
        ],
        "name": {
          "formatted_name": "<string>",
          "first_name": "<string>",
          "last_name": "<string>",
          "middle_name": "<string>",
          "suffix": "<string>",
          "prefix": "<string>"
        },
        "org": {
          "company": "<string>",
          "department": "<string>",
          "title": "<string>"
        },
        "phones": [
          {
            "phone": "<string>",
            "type": "<string>",
            "wa_id": "<string>"
          }
        ],
        "urls": [
          {
            "url": "<string>",
            "type": "<string>"
          }
        ],
        "vcard": "<string>",
        "origin": "contact_request"
      }
    ],
    "reaction": {
      "message_id": "wamid.BgNODYxN...",
      "emoji": "<string>"
    },
    "context": {
      "message_id": "wamid.BgNODYxN..."
    },
    "externalId": "<string>",
    "category": "utility",
    "ttlSeconds": 600,
    "status": "accepted",
    "errorCode": "INTERNAL_SERVER_ERROR",
    "errorMessage": "<string>",
    "createTime": "2022-06-01T12:00:00.000Z",
    "updateTime": "2022-06-01T12:00:00.000Z",
    "sendTime": "2022-06-01T12:00:00.000Z",
    "deliverTime": "2022-06-01T12:00:00.000Z",
    "readTime": "2022-06-01T12:00:00.000Z",
    "totalPrice": 0.05,
    "currency": "USD",
    "regionCode": "US",
    "pricingCategory": "referral_conversion",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "whatsappApiError": {
      "message": "HSM Template creation failed",
      "code": 200002,
      "type": "OAuthException",
      "error_subcode": 2388109,
      "error_user_msg": "This message template cannot be created.",
      "error_user_title": "Message Cannot Be Submitted",
      "fbtrace_id": "AVGjJ7ia2zJkrHG",
      "error_data": "<string>"
    },
    "bizType": "whatsapp",
    "verificationId": "VERIFICATION-ID"
  }
}

whatsapp.phone_number.deleted

{
  "id": "evt_1234567890",
  "type": "whatsapp.phone_number.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "not_set",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "<string>",
    "verifiedName": "John’s Cake Shop",
    "codeVerificationStatus": "VERIFIED",
    "isOfficialBusinessAccount": false,
    "status": "PENDING",
    "nameStatus": "APPROVED",
    "newNameStatus": "APPROVED",
    "decision": "APPROVED",
    "requestedVerifiedName": "<string>",
    "rejectionReason": "<string>",
    "qualityUpdateEvent": "ONBOARDING",
    "updateEvent": "ACCOUNT_OFFBOARDED",
    "throughputLevel": "HIGH"
  }
}

whatsapp.phone_number.name_updated

{
  "id": "evt_1234567890",
  "type": "whatsapp.phone_number.name_updated",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "not_set",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "<string>",
    "verifiedName": "John’s Cake Shop",
    "codeVerificationStatus": "VERIFIED",
    "isOfficialBusinessAccount": false,
    "status": "PENDING",
    "nameStatus": "APPROVED",
    "newNameStatus": "APPROVED",
    "decision": "APPROVED",
    "requestedVerifiedName": "<string>",
    "rejectionReason": "<string>",
    "qualityUpdateEvent": "ONBOARDING",
    "updateEvent": "ACCOUNT_OFFBOARDED",
    "throughputLevel": "HIGH"
  }
}

whatsapp.template.category_updated

{
  "id": "evt_1234567890",
  "type": "whatsapp.template.category_updated",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "<string>",
    "language": "en_US",
    "category": "AUTHENTICATION",
    "subCategory": "ORDER_STATUS",
    "previousCategory": "<string>",
    "messageSendTtlSeconds": 600,
    "components": [
      {
        "type": "BODY",
        "format": "TEXT",
        "text": "<string>",
        "buttons": [
          {
            "type": "PHONE_NUMBER",
            "text": "<string>",
            "url": "<string>",
            "phone_number": 15550051310,
            "otp_type": "COPY_CODE",
            "autofill_text": "Autofill",
            "package_name": "com.example.myapplication",
            "signature_hash": "K8a%2FAINcGX7",
            "zero_tap_terms_accepted": false,
            "example": [
              "<string>"
            ],
            "flow_id": "1",
            "flow_name": "<string>",
            "flow_json": "<string>",
            "flow_action": "navigate",
            "navigate_screen": "WELCOME_SCREEN"
          }
        ],
        "add_security_recommendation": false,
        "code_expiration_minutes": 5,
        "limited_time_offer": {
          "text": "Expiring offer!",
          "has_expiration": false
        },
        "example": {
          "body_text": [
            [
              "<string>"
            ]
          ],
          "header_text": [
            "<string>"
          ],
          "header_url": [
            "<string>"
          ]
        },
        "cards": [
          {
            "components": [
              {
                "type": "BODY",
                "format": "IMAGE",
                "text": "<string>",
                "buttons": [
                  {
                    "text": "<string>",
                    "url": "<string>",
                    "phone_number": 15550051310,
                    "autofill_text": "Autofill",
                    "package_name": "com.example.myapplication",
                    "signature_hash": "K8a%2FAINcGX7",
                    "zero_tap_terms_accepted": false,
                    "example": [],
                    "flow_id": "1",
                    "flow_name": "<string>",
                    "flow_json": "<string>",
                    "flow_action": "navigate",
                    "navigate_screen": "WELCOME_SCREEN"
                  }
                ],
                "example": {
                  "body_text": [
                    []
                  ],
                  "header_text": [
                    "<string>"
                  ],
                  "header_url": [
                    "<string>"
                  ]
                }
              }
            ]
          }
        ]
      }
    ],
    "status": "REJECTED",
    "qualityRating": "GREEN",
    "reason": "<string>",
    "createTime": "2022-06-01T12:00:00.000Z",
    "updateTime": "2022-06-01T12:00:00.000Z",
    "statusUpdateEvent": "PENDING",
    "disableDate": "December 9, 2022",
    "whatsappApiError": {
      "message": "HSM Template creation failed",
      "code": 200002,
      "type": "OAuthException",
      "error_subcode": 2388109,
      "error_user_msg": "This message template cannot be created.",
      "error_user_title": "Message Cannot Be Submitted",
      "fbtrace_id": "AVGjJ7ia2zJkrHG",
      "error_data": "<string>"
    }
  }
}

whatsapp.template.quality_updated

{
  "id": "evt_1234567890",
  "type": "whatsapp.template.quality_updated",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "<string>",
    "language": "en_US",
    "category": "AUTHENTICATION",
    "subCategory": "ORDER_STATUS",
    "previousCategory": "<string>",
    "messageSendTtlSeconds": 600,
    "components": [
      {
        "type": "BODY",
        "format": "TEXT",
        "text": "<string>",
        "buttons": [
          {
            "type": "PHONE_NUMBER",
            "text": "<string>",
            "url": "<string>",
            "phone_number": 15550051310,
            "otp_type": "COPY_CODE",
            "autofill_text": "Autofill",
            "package_name": "com.example.myapplication",
            "signature_hash": "K8a%2FAINcGX7",
            "zero_tap_terms_accepted": false,
            "example": [
              "<string>"
            ],
            "flow_id": "1",
            "flow_name": "<string>",
            "flow_json": "<string>",
            "flow_action": "navigate",
            "navigate_screen": "WELCOME_SCREEN"
          }
        ],
        "add_security_recommendation": false,
        "code_expiration_minutes": 5,
        "limited_time_offer": {
          "text": "Expiring offer!",
          "has_expiration": false
        },
        "example": {
          "body_text": [
            [
              "<string>"
            ]
          ],
          "header_text": [
            "<string>"
          ],
          "header_url": [
            "<string>"
          ]
        },
        "cards": [
          {
            "components": [
              {
                "type": "BODY",
                "format": "IMAGE",
                "text": "<string>",
                "buttons": [
                  {
                    "text": "<string>",
                    "url": "<string>",
                    "phone_number": 15550051310,
                    "autofill_text": "Autofill",
                    "package_name": "com.example.myapplication",
                    "signature_hash": "K8a%2FAINcGX7",
                    "zero_tap_terms_accepted": false,
                    "example": [],
                    "flow_id": "1",
                    "flow_name": "<string>",
                    "flow_json": "<string>",
                    "flow_action": "navigate",
                    "navigate_screen": "WELCOME_SCREEN"
                  }
                ],
                "example": {
                  "body_text": [
                    []
                  ],
                  "header_text": [
                    "<string>"
                  ],
                  "header_url": [
                    "<string>"
                  ]
                }
              }
            ]
          }
        ]
      }
    ],
    "status": "REJECTED",
    "qualityRating": "GREEN",
    "reason": "<string>",
    "createTime": "2022-06-01T12:00:00.000Z",
    "updateTime": "2022-06-01T12:00:00.000Z",
    "statusUpdateEvent": "PENDING",
    "disableDate": "December 9, 2022",
    "whatsappApiError": {
      "message": "HSM Template creation failed",
      "code": 200002,
      "type": "OAuthException",
      "error_subcode": 2388109,
      "error_user_msg": "This message template cannot be created.",
      "error_user_title": "Message Cannot Be Submitted",
      "fbtrace_id": "AVGjJ7ia2zJkrHG",
      "error_data": "<string>"
    }
  }
}

whatsapp.flow.status_change

{
  "id": "evt_1234567890",
  "type": "whatsapp.flow.status_change",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "flowChanges": {
    "flowId": "1097420589034000",
    "wabaId": "<string>",
    "message": "Flow Webhook 3 changed status from DRAFT to PUBLISHED",
    "oldStatus": "DRAFT",
    "newStatus": "PUBLISHED"
  }
}

whatsapp.payment.updated

{
  "id": "evt_1234567890",
  "type": "whatsapp.payment.updated",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappPayment": {
    "wabaId": "<string>",
    "referenceId": "<string>",
    "status": "captured",
    "transactions": [
      {
        "id": "<string>",
        "type": "billdesk",
        "status": "pending",
        "createdTimestamp": 0,
        "updatedTimestamp": 0,
        "amount": {
          "offset": 100,
          "value": 1234,
          "description": "<string>",
          "discount_program_name": "<string>"
        },
        "currency": "<string>",
        "methodType": "upi",
        "error": {
          "code": "<string>",
          "reason": "<string>"
        }
      }
    ]
  }
}

whatsapp.user.preferences

{
  "id": "evt_1234567890",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappUserPreference": {
    "wabaId": 1234123123,
    "businessPhoneNumber": "+16315551111",
    "businessPhoneId": "1234567890123456",
    "contactName": "John",
    "contactPhoneNumber": "+16315551111",
    "userId": "US.13491208655302741918",
    "parentUserId": "US.ENT.11815799212886844830",
    "detail": "User requested to stop marketing messages",
    "category": "marketing_messages",
    "value": "stop",
    "timestamp": "1739321024000"
  }
}

开始使用

指南

接口

Webhooks

这是什么

工作原理

请求

响应

载荷目录

​这是什么

​工作原理

​请求

​响应

​载荷目录

这是什么

工作原理

请求

响应

载荷目录