Примеры Webhook для входящих сообщений WhatsApp

Полный каталог, сгенерированный на основе схемы, см. в разделе все примеры.

Что это такое

Обработка входящих типов сообщений WhatsApp с примерами полезной нагрузки и пояснениями.

Перед началом работы

Создайте публичный эндпоинт HTTPS в вашем приложении.
Настройте эндпоинт Webhook в YCloud для необходимых типов событий.
Обеспечьте безопасное хранение секрета подписи эндпоинта.
Сделайте обработку событий идемпотентной.

Как это работает

YCloud отправляет HTTP-запрос POST при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ 2xx и выполняйте длительные операции асинхронно.

Запрос

Ниже приведены сценарии запросов, отправляемых на ваш Webhook URL. Используйте id события как идентификатор доставки, а type — для маршрутизации полезной нагрузки.

Ответ

Возвращайте статус 2xx после успешного принятия события.

HTTP/1.1 200 OK

Информацию о настройке эндпоинта, проверке подписи и поведении повторных попыток см. в разделе Настройка вебхуков.

Входящее неподдерживаемое сообщение

В этом случае ваш эндпоинт 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 получил входящее текстовое сообщение:

Содержит обычный текст, отправленный пользователем.
Содержит информацию об упомянутом сообщении в 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 — это исходный ID упомянутого сообщения на платформе WhatsApp, начинающийся с wamid..

Входящее текстовое сообщение, инициированное кликом по рекламе WhatsApp Ads

В этом случае ваш эндпоинт 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 файл доступен напрямую в течение нескольких минут для удобства клиента, однако для скачивания файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

Входящее сообщение с видео

В этом случае ваш эндпоинт 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 файл доступен напрямую в течение нескольких минут для удобства клиента, однако для скачивания файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

Входящее аудиосообщение

В этом случае ваш эндпоинт 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 файл доступен напрямую в течение нескольких минут для удобства клиента, однако для скачивания файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

Входящее сообщение с документом

В этом случае ваш эндпоинт 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 файл доступен напрямую в течение нескольких минут для удобства клиента, однако для скачивания файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

Входящее сообщение со стикером

В этом случае ваш эндпоинт 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 можно напрямую обращаться в течение нескольких минут для удобства получателя, однако для загрузки этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

Входящее сообщение с геопозицией (Location)

В этом случае ваша конечная точка 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 и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Входящее сообщение с контактами (Contacts)

В этом случае ваша конечная точка 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

Объяснение

Входящее сообщение-реакция (Reaction)

В этом случае ваша конечная точка 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 присутствует, когда пользователь реагирует на сообщение с помощью эмодзи. Его отсутствие означает, что пользователь удалил эмодзи с сообщения.

Входящее сообщение по нажатию кнопки шаблона (Template Button)

В этом случае ваша конечная точка 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

Объяснение

Входящее интерактивное сообщение с выбором из списка (Interactive List Reply)

В этом случае ваша конечная точка 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 — исходный ID сообщения на платформе WhatsApp, начинающийся с wamid..

Входящее интерактивное сообщение с ответом по кнопке (Interactive Button Reply)

В этом случае ваша конечная точка 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 — исходный ID сообщения на платформе WhatsApp, начинающийся с wamid..

Входящее интерактивное сообщение с ответом Flow (Interactive Flow Response)

После завершения 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. Структура определяется либо в JSON flow (см. действие Complete), либо, если flow использует конечную точку, управляется этой конечной точкой (см. Final Response Payload в разделе Data Exchange Request). Распарсите JSON-строку interactive.response_json в объект JSON, значения которого могут иметь различные типы данных. Как правило, значения представляют собой обычный текст, за исключением:
- Когда данные поступают из компонента CheckboxGroup, значение представляет собой список строк.
- Если оно исходит от компонента OptIn, значением является логическое значение (boolean), то есть true или false. В настоящее время, если оно присутствует, значение всегда должно быть true, поскольку такой ключ не будет включен в 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

Объяснение

Входящее сообщение с запросом информации о товаре

В этом случае ваша конечная точка 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) поступает, когда пользователь запрашивает подробные сведения о конкретном товаре. Это происходит в двух сценариях:
- Когда клиент отвечает на сообщения с одним или несколькими товарами.
- Когда клиент переходит в каталог компании через другую точку входа, открывает страницу сведений о товаре и нажимает «Написать компании об этом товаре».

Входящее сообщение Request Welcome

Вы можете получать уведомления через Webhook всякий раз, когда пользователь WhatsApp впервые открывает чат с вами. Это удобно, если вы хотите отправить таким пользователям специально настроенное приветственное сообщение. Если вы включите эту функцию и пользователь откроет чат (как правило, при переходе по универсальной ссылке, такой как ссылки wa.me или api.whatsapp.com ), клиент WhatsApp проверяет наличие существующей переписки между пользователем и вашим рабочим номером телефона. Если переписки нет, клиент активирует Webhook request_welcome. После этого вы можете отправить пользователю собственное приветственное сообщение. 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 Manager > Номера телефонов > Настройки > Автоматизация.
Для тестирования сообщения request_welcome, если у вас уже есть история чата с данным номером компании, сначала необходимо удалить этот чат.
Эта функция только инициирует входящее сообщение request_welcome и не отправляет никаких сообщений автоматически в ответ. Отправлять ли приветственное сообщение — решать вам.

​Что это такое

​Перед началом работы

​Как это работает

​Запрос

​Ответ

​Входящее неподдерживаемое сообщение

​Запрос

​Ответ

​Пояснение

​Входящее текстовое сообщение

​Запрос

​Ответ

​Пояснение

​Входящее текстовое сообщение, инициированное кликом по рекламе WhatsApp Ads

​Запрос

​Ответ

​Пояснение

​Входящее сообщение с изображением

​Запрос

​Ответ

​Пояснение

​Входящее сообщение с видео

​Запрос

​Ответ

​Пояснение

​Входящее аудиосообщение

​Запрос

​Ответ

​Пояснение

​Входящее сообщение с документом

​Запрос

​Ответ

​Пояснение

​Входящее сообщение со стикером

​Запрос

​Ответ

​Объяснение

​Входящее сообщение с геопозицией (Location)

​Запрос

​Ответ

​Объяснение

​Входящее сообщение с контактами (Contacts)

​Запрос

​Ответ

​Объяснение

​Входящее сообщение-реакция (Reaction)

​Запрос

​Ответ

​Объяснение

​Входящее сообщение по нажатию кнопки шаблона (Template Button)

​Запрос

​Ответ

​Объяснение

​Входящее интерактивное сообщение с выбором из списка (Interactive List Reply)

​Запрос

​Ответ

​Объяснение

​Входящее интерактивное сообщение с ответом по кнопке (Interactive Button Reply)

​Запрос

​Ответ

​Объяснение

​Входящее интерактивное сообщение с ответом Flow (Interactive Flow Response)

​Запрос

​Ответ

​Объяснение

​Входящее системное сообщение

​Запрос

​Ответ

​Объяснение

​Входящее сообщение заказа

​Запрос

​Ответ

​Объяснение

​Входящее сообщение с запросом информации о товаре

​Запрос

​Ответ

​Объяснение

​Входящее сообщение Request Welcome

​Запрос

​Ответ

Что это такое

Перед началом работы

Как это работает

Запрос

Ответ

Входящее неподдерживаемое сообщение

Запрос

Ответ

Пояснение

Входящее текстовое сообщение

Запрос

Ответ

Пояснение

Входящее текстовое сообщение, инициированное кликом по рекламе WhatsApp Ads

Запрос

Ответ

Пояснение

Входящее сообщение с изображением

Запрос

Ответ

Пояснение

Входящее сообщение с видео

Запрос

Ответ

Пояснение

Входящее аудиосообщение

Запрос

Ответ

Пояснение

Входящее сообщение с документом

Запрос

Ответ

Пояснение

Входящее сообщение со стикером

Запрос

Ответ

Объяснение

Входящее сообщение с геопозицией (Location)

Запрос

Ответ

Объяснение

Входящее сообщение с контактами (Contacts)

Запрос

Ответ

Объяснение

Входящее сообщение-реакция (Reaction)

Запрос

Ответ

Объяснение

Входящее сообщение по нажатию кнопки шаблона (Template Button)

Запрос

Ответ

Объяснение

Входящее интерактивное сообщение с выбором из списка (Interactive List Reply)

Запрос

Ответ

Объяснение

Входящее интерактивное сообщение с ответом по кнопке (Interactive Button Reply)

Запрос

Ответ

Объяснение

Входящее интерактивное сообщение с ответом Flow (Interactive Flow Response)

Запрос

Ответ

Объяснение

Входящее системное сообщение

Запрос

Ответ

Объяснение

Входящее сообщение заказа

Запрос

Ответ

Объяснение

Входящее сообщение с запросом информации о товаре

Запрос

Ответ

Объяснение

Входящее сообщение Request Welcome

Запрос

Ответ