WhatsApp 入站消息 Webhook 示例

有关基于架构派生的完整目录，请参阅所有示例。

功能介绍

通过带有注释的有效负载示例处理入站 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

说明

错误 131051 及 Message type unknown 表示 WhatsApp Cloud API 不支持该消息类型。
错误 131060 及 This message is currently unavailable. 表示 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 包含有关广告的信息。另请参阅 Click to 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 进行去重，并将耗时或易失败的工作转移至异步处理器。

入站 Reaction 消息

在此情况下，您的 Webhook 端点收到了入站 Reaction 消息：

包含用户做出反应的消息 ID。
包含 emoji 表情。

请求

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 对消息作出反应时，存在 emoji。如果不存在，则表示用户移除了对消息的 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 action），要么（如果 Flow 使用了端点）由端点控制（参见 Data Exchange Request 中的 Final Response Payload）。将 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。仅当启用了父级 BSUID 时才会包含 parent_user_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": "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

说明

当用户咨询特定商品的更多信息时，将收到商品咨询消息（Product Inquiry Message）。该消息可能在以下两种情况下收到：
- 客户回复单商品或多商品消息时。
- 客户通过其他入口访问商家的商品目录，进入商品详情页面，并点击“向商家发送关于此商品的消息”时。

入站请求欢迎消息

每当 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 消息，不会自动回复任何消息。是否回复欢迎消息完全由您决定。

​功能介绍

​准备工作

​工作原理

​请求

​响应

​入站不支持的消息

​请求

​响应

​说明

​入站文本消息

​请求

​响应

​说明

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

​请求

​响应

​说明

​入站图片消息

​请求

​响应

​说明

​入站视频消息

​请求

​响应

​说明

​入站音频消息

​请求

​响应

​说明

​入站文档消息

​请求

​响应

​说明

​入站贴纸消息

​请求

​响应

​说明

​入站位置消息

​请求

​响应

​说明

​入站联系人消息

​请求

​响应

​说明

​入站 Reaction 消息

​请求

​响应

​说明

​入站模板按钮消息

​请求

​响应

​说明

​入站交互式列表回复消息

​请求

​响应

​说明

​入站交互式按钮回复消息

​请求

​响应

​说明

​入站交互式 Flow 响应消息

​请求

​响应

​说明

​入站系统消息

​请求

​响应

​说明

​入站订单消息

​请求

​响应

​说明

​入站商品咨询消息

​请求

​响应

​说明

​入站请求欢迎消息

​请求

​响应

功能介绍

准备工作

工作原理

请求

响应

入站不支持的消息

请求

响应

说明

入站文本消息

请求

响应

说明

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

请求

响应

说明

入站图片消息

请求

响应

说明

入站视频消息

请求

响应

说明

入站音频消息

请求

响应

说明

入站文档消息

请求

响应

说明

入站贴纸消息

请求

响应

说明

入站位置消息

请求

响应

说明

入站联系人消息

请求

响应

说明

入站 Reaction 消息

请求

响应

说明

入站模板按钮消息

请求

响应

说明

入站交互式列表回复消息

请求

响应

说明

入站交互式按钮回复消息

请求

响应

说明

入站交互式 Flow 响应消息

请求

响应

说明

入站系统消息

请求

响应

说明

入站订单消息

请求

响应

说明

入站商品咨询消息

请求

响应

说明

入站请求欢迎消息

请求

响应