入站消息和偏好 Webhook 示例

如需查看基于架构生成的完整目录，请参阅所有示例。

概述

处理 WhatsApp、Messenger 和 SMS 入站消息，以及 WhatsApp 营销偏好。

准备工作

在您的应用程序中创建一个公开的 HTTPS 端点。
为您所需的事件类型配置 YCloud Webhook 端点。
安全存储端点签名密钥。
确保事件处理具有幂等性。

工作原理

事件发生时，YCloud 会发送 HTTP POST 请求。请验证签名、持久化记录事件、返回 2xx 响应，并异步处理耗时任务。

请求

以下场景展示了发送至您的 Webhook URL 的请求。将事件 id 用作投递标识符，并使用 type 路由有效载荷。

响应

接收事件后返回 2xx 状态。

HTTP/1.1 200 OK

有关端点设置、签名验证和重试机制，请参阅配置 Webhook。

入站不支持的消息

在这种情况下，您的 Webhook 端点收到了一条入站的不支持消息：

type 设置为 unsupported。
errors 说明了消息不支持或不可用的原因。
unsupported.type 标识消息类别，例如 poll_creation、poll_update、edit 或 pin。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f8709b741c165b4342a714",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "errors": [
       {
          "code": 131051,
          "title": "Message type unknown",
          "message": "Message type unknown",
          "error_data": {
             "details": "Message type is currently not supported."
          }
       }
     ],
     "type": "unsupported",
     "unsupported": {
       "type": "poll_update"
     }
  }
}'

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

包含 Message type unknown 的错误 131051 表示 WhatsApp Cloud API 不支持该消息类型。
包含 This message is currently unavailable. 的错误 131060 表示 WhatsApp 无法提供该消息内容。
unsupported.type 标识大体类别。它不包含原始消息内容。
如需查看消息类型的易读列表，请参阅收件箱中不受支持的消息。有关当前的有效载荷规范，请参阅 Meta 的不受支持的消息 Webhook 参考。

入站文本消息

在这种情况下，您的 Webhook 端点收到了一条入站文本消息：

包含用户发送的纯文本。
在 context 中包含所引用消息的信息。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

入站消息是指客户向您的商业电话号码发送的消息。
context（可选）包含所提及消息的信息，通常用于回复用户或您的企业先前发送的消息。
- context.from 是发送所提及消息的用户的 WhatsApp ID（不带“+”前缀的电话号码）。
- context.id 是所提及消息在 WhatsApp 平台上的原始 ID，以 wamid. 开头。

点击 WhatsApp 广告触发的入站文本消息

在这种情况下，您的 Webhook 端点收到了一条因点击 WhatsApp 广告而触发的入站文本消息：

包含纯文本。
包含广告相关信息。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "referral": {
      "source_url": "https://fb.me/xxx",
      "source_type": "ad",
      "source_id": "MEDIA-ID",
      "headline": "Chat with us",
      "media_type": "image",
      "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/xxx.jpg",
      "ctwa_clid": "feRgX__yiYtsI1HhjI2FRjyKInYlrU9cm9ml-Yl1MXp_fJy6Mwp-adZ-yLqOWX5CiZJYtjQERgKbAUetcwFXb_6FUYyOl9Kc6HFOBCd"
    }
  }
}'

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

referral 包含有关广告的信息。另请参阅点击跳转 WhatsApp 广告。

入站图片消息

在这种情况下，您的 Webhook 端点收到了一条入站图片消息：

包含图片 URL。
包含描述该图片的说明文字。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkv5wsCJItpaH01",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87878509703399f3fd3d0",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/592623615738103?sig=t%3D1677228150%2Cs%3D0aa4810392602afb2a91e28e54223c4c0e638bba298f19f07a6c3a2ccf6bdf1e&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODc4Nzg1MDk3MDMzOTlmM2ZkM2QwIiwibWltZVR5cGUiOiJpbWFnZS9qcGVnIiwic2hhMjU2IjoiTGVScFFKcS9oNEhUam1QOHNtRkpRRXdZQm5rR0JVdDFjeDRxekZjblVoUT0ifQ",
      "caption": "Go for a walk.",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=",
      "mime_type": "image/jpeg"
    }
  }
}'

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

为了方便使用者，image.link 可以在几分钟内直接访问，但您始终应该包含 X-API-Key 请求头以在 30 天内下载该文件。

入站视频消息

在这种情况下，您的 Webhook 端点收到了一条入站视频消息：

包含视频 URL。
包含描述该视频的说明文字。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkwhYtqMPmYdsN3",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87991741c165b4342a797",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "video",
    "video": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/919306472440541?sig=t%3D1677228430%2Cs%3D481b972ebc10e6b384f11274ba59e64b8c355543ea0b30e066b209361212abad&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODc5OTE3NDFjMTY1YjQzNDJhNzk3IiwibWltZVR5cGUiOiJ2aWRlby9tcDQiLCJzaGEyNTYiOiJ4RHpyU1R1YnZURm53MytzMVdJbEFiSUZLanpBS2k1dFZWaVFOVjhKV3BnPSJ9",
      "caption": "Go for a walk.",
      "id": "919306472440541",
      "sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=",
      "mime_type": "video/mp4"
    }
  }
}'

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

为了方便使用者，video.link 可以在几分钟内直接访问，但您始终应该包含 X-API-Key 请求头以在 30 天内下载该文件。

入站音频消息

在这种情况下，您的 Webhook 端点收到了一条入站音频消息：

包含音频 URL。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEl1TDAcquZUxzLn",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87cd3509703399f3fd3f2",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "audio",
    "audio": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/712063723747110?sig=t%3D1677229265%2Cs%3D5c6a65172ef8caa7bc969dacb831d6e15362fd7a5b6be7aa994aa83cdd15fc4e&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODdjZDM1MDk3MDMzOTlmM2ZkM2YyIiwibWltZVR5cGUiOiJhdWRpby9tcGVnIiwic2hhMjU2IjoiQWtSWkR5dEx5MkkxSzFkT2VMNnBRT2pZblBwcGdqdFNDTzlNUStDcnkwUT0ifQ",
      "id": "712063723747110",
      "sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=",
      "mime_type": "audio/mpeg"
    }
  }
}'

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

为了方便使用者，audio.link 可以在几分钟内直接访问，但您始终应该包含 X-API-Key 请求头以在 30 天内下载该文件。

入站文档消息

在这种情况下，您的 Webhook 端点收到了一条入站文档消息：

包含文档 URL。
包含描述该文档的说明文字。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkz3y7V6TCqgkbK",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87b2e741c165b4342a79b",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "document",
    "document": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/948915536111569?sig=t%3D1677228843%2Cs%3D6eb8b4fc2796bae9f2e95702fbbd4d211cace96bc5c934a12d97704140e47a16&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODdiMmU3NDFjMTY1YjQzNDJhNzliIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9wZGYiLCJzaGEyNTYiOiJFcHZDdHpUallkcTRleG1xc2ZHYmVpK1NUZ1h4VnFUQzJ0b2laODB2bW5rPSJ9",
      "caption": "PDF example",
      "filename": "sample.pdf",
      "id": "948915536111569",
      "sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=",
      "mime_type": "application/pdf"
    }
  }
}'

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

为了方便使用者，document.link 可以在几分钟内直接访问，但您始终应该包含 X-API-Key 请求头以在 30 天内下载该文件。

入站贴纸消息

在这种情况下，您的 Webhook 端点收到了一条入站贴纸消息：

包含贴纸 URL。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc1678741c165b4342b38e",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "sticker",
    "sticker": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/729118992174848?sig=t%3D1677465205%2Cs%3Dbc0d582e37cc701d5d090c1d11aa7eaed9b3f8e83925425a82d0aaab8b7da258&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmYzE2Nzg3NDFjMTY1YjQzNDJiMzhlIiwibWltZVR5cGUiOiJpbWFnZS93ZWJwIiwic2hhMjU2IjoiUlpFRWw1SFZXVDRTNkMwUG9PZ2pZQ1FWRFdzNWVzSU1Kc2pjRFlJODBaRT0ifQ",
      "id": "729118992174848",
      "sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=",
      "mime_type": "image/webp"
    }
  }
}'

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

为方便消费者使用，sticker.link 可以在几分钟内直接访问，但您应始终包含 X-API-Key 请求头，以便在 30 天内下载该文件。

入站位置消息

在此情况下，您的 Webhook 端点收到了一条入站位置消息：

包含该地点的纬度和经度。
包含该地点的名称、地址和 URL。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc18ae509703399f3fe000",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "location",
    "location": {
      "latitude": 1.40435,
      "longitude": 103.79304,
      "name": "Singapore Zoo",
      "address": "80 Mandai Lake Road Singapore 72",
      "url": "https://www.zoo.com.sg"
    }
  }
}'

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

按 type 路由事件，通过 id 对其进行去重，并将缓慢或容易失败的工作转移到异步处理器。

入站联系人消息

在此情况下，您的 Webhook 端点收到了一条入站联系人消息：

包含一个联系人及其地址、生日、电子邮件、姓名、电话及其他联系人字段。
当用户响应请求联系人信息消息而分享联系人时，包含 origin: contact_request。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "street": "<ADDRESS_STREET>",
            "city": "<ADDRESS_CITY>",
            "state": "<ADDRESS_STATE>",
            "zip": "<ADDRESS_ZIP>",
            "country": "<ADDRESS_COUNTRY>",
            "country_code": "<ADDRESS_COUNTRY_CODE>",
            "type": "HOME"
          }
        ],
        "birthday": "2001-01-01",
        "emails": [
          {
            "email": "joe@example.com",
            "type": "WORK"
          }
        ],
        "name": {
          "formatted_name": "<CONTACT_FORMATTED_NAME>",
          "first_name": "<CONTACT_FIRST_NAME>",
          "last_name": "<CONTACT_LAST_NAME>",
          "middle_name": "<CONTACT_MIDDLE_NAME>",
          "suffix": "<CONTACT_SUFFIX>",
          "prefix": "<CONTACT_PREFIX>"
        },
        "org": {
          "company": "<CONTACT_ORG_COMPANY>",
          "department": "<CONTACT_ORG_DEPARTMENT>",
          "title": "<CONTACT_ORG_TITLE>"
        },
        "phones": [
          {
            "phone": "+447901614024",
            "wa_id": "447901614024",
            "type": "WORK"
          }
        ],
        "origin": "contact_request",
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}'

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

按 type 路由事件，通过 id 对其进行去重，并将缓慢或容易失败的工作转移到异步处理器。

入站回应消息

在此情况下，您的 Webhook 端点收到了一条入站回应消息：

包含用户所回应的消息 ID。
包含表情符号。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgNODYxNTcwMDA3NzE0NRUCABIYIEYyMzY3OUJBMzY2RkFFQkRDQjYyQ0Q5RDE1QjA2RUYyAA==",
      "emoji": "👍"
    }
  }
}'

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

当用户使用表情符号回应某条消息时，会出现 emoji。如果不存在，则表示用户移除了对该消息的表情符号回应。

入站模板按钮消息

在此情况下，您的 Webhook 端点收到了一条入站模板按钮消息：

包含您在发送模板消息时所使用的模板按钮 text。
包含您在发送模板消息时提供的按钮 payload。
包含您发送的模板消息的 wamid（context.wamid）。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "button",
    "button": {
      "payload": "more_about_marketing_friday",
      "text": "Learn more"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

按 type 路由事件，通过 id 对其进行去重，并将缓慢或容易失败的工作转移到异步处理器。

入站互动列表回复消息

在此情况下，您的 Webhook 端点收到了一条入站互动列表回复消息：

interactive 字段包含用户在您之前发送的互动消息中所点击的列表回复项。
context 字段包含有关您先前发送给用户的互动消息的信息。

点击按钮选择一项。

收件人通过选择您先前发送的互动消息中的某个选项来回复您的消息。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f73942741c165b43429f86",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "list_reply",
      "list_reply": {
        "id": "<LIST_SECTION_2_ROW_1_ID>",
        "title": "<SECTION_2_ROW_1_TITLE>",
        "description": "<SECTION_2_ROW_1_DESC>"
      }
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

context 包含有关您先前发送的互动消息的信息。
- context.from 是发送该互动消息者的 WhatsApp ID（不带“+”前缀的电话号码）。
- context.id 是 WhatsApp 平台上的原始消息 ID，以 wamid. 开头。

入站互动按钮回复消息

在此情况下，您的 Webhook 端点收到了一条入站互动按钮回复消息：

interactive 字段包含用户在您先前发送的互动消息中点击的按钮回复。
context 字段包含有关您先前发送给用户的互动消息的信息。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "<UNIQUE_BUTTON_ID_2>",
        "title": "<BUTTON_TITLE_2>"
      }
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

context 包含有关您先前发送的互动消息的信息。
- context.from 是发送该互动消息者的 WhatsApp ID（不带“+”前缀的电话号码）。
- context.id 是 WhatsApp 平台上的原始消息 ID，以 wamid. 开头。

入站互动 Flow 响应消息

Flow 完成后，系统将向 WhatsApp 聊天发送一条响应消息。您将以接收用户其他所有消息相同的方式接收该消息——即通过消息 Webhook。response_json 字段将包含 Flow 专属数据。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "nfm_reply",
      "nfm_reply": {
        "name": "flow",
        "body": "Sent",
        "response_json": "{\"flow_token\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
      }
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

响应

在持久化接收事件后确认交付。

HTTP/1.1 200 OK

说明

interactive.type 始终为 nfm_reply。interactive.name 始终为 flow。interactive.body 始终为 Sent。
interactive.response_json 为 Flow 专属数据。其结构要么在 Flow JSON 中定义（参见 Complete 操作），要么在 Flow 使用端点时由端点控制（参见数据交换请求中的最终响应有效负载）。将 interactive.response_json JSON 字符串解析为 JSON 对象，其值的数据类型可以多样。通常情况下，值是纯文本，除了以下情况：
- 当其源自 CheckboxGroup 组件时，该值为字符串列表。
- 当它来自 OptIn 组件时，该值为布尔值，即 true 或 false。目前，如果存在，该值必须为 true，因为如果用户未选择加入（opt in），response_json 中将不会包含此类键。
- 当它来自 DatePicker 组件时，该值为表示毫秒级 Unix 时间戳的字符串，例如 "1725936737548"（即 2024-09-10T02:52:17.548Z）。从 Flow JSON 版本 5.0 开始，日期将采用 “yyyy-MM-dd” 格式设置，这使得这些值与时区无关。
要发送带有 Flow 的消息，请参阅 Flow 模板消息和交互式 Flow 消息。

入站系统消息

在这种情况下，您的 Webhook 端点收到了入站系统消息：

type 设置为 system，并且 system.type 设置为 user_changed_number。
用户在 WhatsApp 上更改了其电话号码，wa_id 是新的 WhatsApp ID（不带 + 前缀的电话号码）。
user_id 是新的 BSUID。parent_user_id 仅在启用父级 BSUID 时包含。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "system",
    "system": {
      "body": "User A changed from 123456789 to 987654321",
      "wa_id": "987654321",
      "user_id": "US.13491208655302741919",
      "parent_user_id": "US.ENT.11815799212886844831",
      "type": "user_changed_number"
    }
  }
}'

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 对其去重，并将缓慢或易失败的工作移交给异步处理器。

入站订单消息

在这种情况下，当客户将一种或多种商品添加到购物车并提交订单时，您的 Webhook 端点会收到入站订单消息：

包含有关所订购商品的信息。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "order",
    "order": {
      "catalog_id": "the-catalog_id",
      "product_items": [
        {
          "product_retailer_id": "the-product-SKU-identifier",
          "quantity": "number-of-item",
          "item_price": "unitary-price-of-item",
          "currency": "price-currency"
        }
      ],
      "text": "text-message-sent-along-with-the-order"
    },
    "context": {
      "from": "16315551234",
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
    }
  }
}'

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 对其去重，并将缓慢或易失败的工作移交给异步处理器。

入站商品咨询消息

在这种情况下，当客户咨询商品时，您的 Webhook 端点会收到一条入站文本消息：

包含有关该商品的信息。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "Can I get this in another color?"
    },
    "context": {
      "referred_product": {
        "catalog_id": "catalog-ID",
        "product_retailer_id": "product-ID"
      }
    }
  }
}'

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

当用户询问有关特定商品的更多信息时，将收到商品咨询消息。这些消息可能在两种情况下收到：
- 当客户回复单商品或多商品消息时。
- 当客户通过其他入口点访问商家目录，导航至商品详情页面，并点击“向商家咨询此商品”时。

入站请求欢迎消息

每当 WhatsApp 用户首次与您发起聊天时，您都可以通过 Webhook 收到通知。如果您想向这些用户回复您自行设计的特别欢迎消息，这会非常有用。如果您启用了此功能且用户发起了聊天（通常是用户点击了通用链接，即 wa.me 或 api.whatsapp.com 链接），WhatsApp 客户端会检查该用户与您的商业电话号码之间是否已有现存的消息会话。如果没有，客户端将触发 request_welcome Webhook。然后，您可以使用自己的欢迎消息回复该用户。 example-inboundmessage-welcomemessage

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "request_welcome"
  }
}'

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

要为电话号码启用此功能，请前往 Meta WhatsApp 管理工具 > 电话号码 > 设置 > 自动化。
要测试 request_welcome 消息，如果您已经与该商业电话号码存在聊天会话，则必须先删除该聊天。
此功能仅触发入站 request_welcome 消息，不会自动回复任何消息。是否回复欢迎消息由您决定。

入站 SMS

当用户回复您的 SMS 时，使用 sms.inbound.received。

请求

{
  "id": "evt_example_sms_inbound_received",
  "type": "sms.inbound.received",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "smsInbound": {
    "id": "sms_inbound_12345678",
    "from": "+16315552222",
    "to": "+16315551111",
    "text": "Please send the order details.",
    "sendTime": "2026-05-26T11:59:00.000Z"
  }
}

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

从 smsInbound.text 读取回复。from 是用户的电话号码，to 是您注册的 Sender ID，sendTime 是消息发送时间。不要将此事件解析为 whatsappInboundMessage。

WhatsApp 营销偏好设置

当 WhatsApp 用户停止或恢复接收营销消息时，使用 whatsapp.user.preferences。

请求

{
  "id": "evt_example_whatsapp_user_preferences",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappUserPreference": {
    "wabaId": "whatsapp-business-account-id",
    "businessPhoneNumber": "+16315551111",
    "businessPhoneId": "1234567890123456",
    "contactName": "Example customer",
    "contactPhoneNumber": "+16315552222",
    "userId": "US.13491208655302741918",
    "parentUserId": "US.ENT.11815799212886844830",
    "detail": "User requested to stop marketing messages",
    "category": "marketing_messages",
    "value": "stop",
    "timestamp": "1779796800000"
  }
}

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

从 whatsappUserPreference 读取 category 和 value；此示例记录了停止接收营销消息的请求。使用商业标识符和提供的客户标识符来匹配偏好设置。未启用父级 BSUID 时将省略 parentUserId。保留 detail 作为解释性文本，并保留提供的 timestamp。这是一个专门的偏好设置事件，而不是入站聊天消息或 contact.unsubscribe.created 负载。

Messenger 入站文本

订阅 messenger.inbound_message.received 以接收普通的一对一文本消息。在接受事件之前验证 YCloud-Signature 请求头。推送重试会保留 Event.id；从同一源事实重新创建事件可能会生成新的 Event.id。通过 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"
  }
}

响应

HTTP/1.1 200 OK

说明

客户 PSID 为 from，Facebook 公共主页 ID 为 to。请原样保留文本，包括空格。sendTime 是保存的源事件时间；createTime 是本地持久化时间。该事件仅携带普通文本消息。源端的重复推送可能会为同一个已保存的消息 ID 创建另一个事件。

Messenger 入站文本编辑

订阅 messenger.inbound_message.updated 以接收现有入站消息的最新文本。在处理有效载荷之前验证 YCloud-Signature。

请求

{
  "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"
  }
}

响应

HTTP/1.1 200 OK

说明

更新记录时请保持相同的消息 id 和 metaMessageId。新的 text.body、累计的 editCount 以及 editTime 描述了已保存的编辑内容。消息 sendTime 和 createTime 保留其原始值；事件 createTime 为编辑时间。未编辑的消息会省略编辑字段。仅更新现有的入站消息；不会重新构建缺失的原始消息和已被取代的编辑版本。推送重试会保留事件 ID，但源端重新处理可能会创建新的事件 ID。使用消息 ID 和编辑计数来处理重复和排序。

​概述

​准备工作

​工作原理

​请求

​响应

​入站不支持的消息

​请求

​响应

​说明

​入站文本消息

​请求

​响应

​说明

​点击 WhatsApp 广告触发的入站文本消息

​请求

​响应

​说明

​入站图片消息

​请求

​响应

​说明

​入站视频消息

​请求

​响应

​说明

​入站音频消息

​请求

​响应

​说明

​入站文档消息

​请求

​响应

​说明

​入站贴纸消息

​请求

​响应

​说明

​入站位置消息

​请求

​响应

​说明

​入站联系人消息

​请求

​响应

​说明

​入站回应消息

​请求

​响应

​说明

​入站模板按钮消息

​请求

​响应

​说明

​入站互动列表回复消息

​请求

​响应

​说明

​入站互动按钮回复消息

​请求

​响应

​说明

​入站互动 Flow 响应消息

​请求

​响应

​说明

​入站系统消息

​请求

​响应

​说明

​入站订单消息

​请求

​响应

​说明

​入站商品咨询消息

​请求

​响应

​说明

​入站请求欢迎消息

​请求

​响应

概述

准备工作

工作原理

请求

响应

入站不支持的消息

请求

响应

说明

入站文本消息

请求

响应

说明

点击 WhatsApp 广告触发的入站文本消息

请求

响应

说明

入站图片消息

请求

响应

说明

入站视频消息

请求

响应

说明

入站音频消息

请求

响应

说明

入站文档消息

请求

响应

说明

入站贴纸消息

请求

响应

说明

入站位置消息

请求

响应

说明

入站联系人消息

请求

响应

说明

入站回应消息

请求

响应

说明

入站模板按钮消息

请求

响应

说明

入站互动列表回复消息

请求

响应

说明

入站互动按钮回复消息

请求

响应

说明

入站互动 Flow 响应消息

请求

响应

说明

入站系统消息

请求

响应

说明

入站订单消息

请求

响应

说明

入站商品咨询消息

请求

响应

说明

入站请求欢迎消息

请求

响应