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

Что это такое

Обработка входящих сообщений WhatsApp, Messenger и SMS, а также маркетинговых предпочтений WhatsApp.

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

  • Создайте общедоступную конечную точку HTTPS в своем приложении.
  • Настройте конечную точку Webhook YCloud для необходимых типов событий.
  • Безопасно сохраните секретный ключ подписи конечной точки.
  • Сделайте обработку событий идемпотентной.

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

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

Request

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

Response

Верните статус 2xx после принятия события.
Сведения о настройке конечной точки, проверке подписи и механизме повторных попыток см. в разделе Настройка Webhook.

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

В этом случае ваша конечная точка Webhook получила входящее неподдерживаемое сообщение:
  • type имеет значение unsupported.
  • errors объясняет, почему сообщение не поддерживается или недоступно.
  • unsupported.type определяет категорию сообщения, например poll_creation, poll_update, edit или pin.

Request

Response

Подтвердите доставку после надежного принятия события.

Пояснение

  • Ошибка 131051 с кодом Message type unknown означает, что WhatsApp Cloud API не поддерживает данный тип сообщений.
  • Ошибка 131060 с кодом This message is currently unavailable. означает, что WhatsApp не смог предоставить содержимое сообщения.
  • unsupported.type определяет общую категорию. Оно не содержит исходного текста сообщения.
  • Удобный список типов сообщений см. в разделе Неподдерживаемые сообщения во Входящих. Актуальный контракт полезной нагрузки см. в справочнике Meta unsupported messages webhook reference.

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

В этом случае ваша конечная точка Webhook получила входящее текстовое сообщение:
  • Содержит простой текст, отправленный пользователем.
  • Содержит информацию об упомянутом сообщении в context.

Request

Response

Подтвердите доставку после надежного принятия события.

Пояснение

  • Входящие сообщения — это сообщения, отправленные клиентами на телефонные номера вашей компании.
  • Поле context (необязательное) содержит информацию об упомянутом сообщении, обычно используемую при ответе на предыдущее сообщение от пользователя или вашей компании.
    • context.from — это WhatsApp ID (номер телефона без префикса «+») пользователя, отправившего упомянутое сообщение.
    • context.id — это исходный идентификатор упомянутого сообщения на платформе WhatsApp, начинающийся с wamid..

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

В этом случае ваша конечная точка Webhook получила входящее текстовое сообщение, отправленное по клику на рекламу в WhatsApp:
  • Содержит обычный текст.
  • Содержит информацию о рекламе.

Request

Response

Подтвердите доставку после надежного принятия события.

Пояснение

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

В этом случае ваша конечная точка Webhook получила входящее сообщение с изображением:
  • Содержит URL изображения.
  • Содержит подпись с описанием этого изображения.

Request

Response

Подтвердите доставку после надежного принятия события.

Пояснение

  • К image.link можно напрямую обращаться в течение нескольких минут для удобства клиента, однако для скачивания этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

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

В этом случае ваша конечная точка Webhook получила входящее видеосообщение:
  • Содержит URL видео.
  • Содержит подпись с описанием этого видео.

Request

Response

Подтвердите доставку после надежного принятия события.

Пояснение

  • К video.link можно напрямую обращаться в течение нескольких минут для удобства клиента, однако для скачивания этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

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

В этом случае ваша конечная точка Webhook получила входящее аудиосообщение:
  • Содержит URL аудиозаписи.

Request

Response

Подтвердите доставку после надежного принятия события.

Пояснение

  • К audio.link можно напрямую обращаться в течение нескольких минут для удобства клиента, однако для скачивания этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

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

В этом случае ваша конечная точка Webhook получила входящее сообщение с документом:
  • Содержит URL документа.
  • Содержит подпись с описанием этого документа.

Request

Response

Подтвердите доставку после надежного принятия события.

Пояснение

  • К document.link можно напрямую обращаться в течение нескольких минут для удобства клиента, однако для скачивания этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

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

В этом случае ваша конечная точка Webhook получила входящее сообщение со стикером:
  • Содержит URL стикера.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

  • Для удобства получателя к sticker.link можно обращаться напрямую в течение нескольких минут, однако для скачивания этого файла в течение 30 дней всегда следует указывать заголовок X-API-Key.

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

В этом случае ваша конечная точка Webhook получила входящее сообщение с геопозицией:
  • Содержит широту и долготу места.
  • Содержит название, адрес и URL места.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

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

В этом случае ваша конечная точка Webhook получила входящее сообщение с контактами:
  • Содержит один контакт с адресами, датой рождения, адресами электронной почты, именем, телефонами и другими полями контакта.
  • Содержит origin: contact_request, если пользователь поделился контактом в ответ на сообщение с запросом контактных данных.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id, и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Входящее сообщение с реакцией

В этом случае ваша конечная точка Webhook получила входящее сообщение с реакцией:
  • Содержит ID сообщения, на которое пользователь отреагировал.
  • Содержит эмодзи.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

  • Поле emoji присутствует, если пользователь отреагировал на сообщение с помощью эмодзи. Его отсутствие указывает на то, что пользователь удалил эмодзи из сообщения.

Входящее сообщение с кнопкой шаблона

В этом случае ваша конечная точка Webhook получила входящее сообщение с кнопкой шаблона:
  • Содержит text кнопки шаблона, который использовался при отправке шаблонного сообщения.
  • Содержит payload кнопки, переданный вами при отправке шаблонного сообщения.
  • Содержит wamid (context.wamid) отправленного вами шаблонного сообщения.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

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

В этом случае ваша конечная точка Webhook получила входящее интерактивное сообщение с ответом из списка (Interactive List Reply):
  • Поле interactive содержит ответ из списка, выбранный пользователем в ранее отправленном вами интерактивном сообщении.
  • Поле context содержит информацию об интерактивном сообщении, ранее отправленном вами пользователю.
Нажмите кнопку, чтобы выбрать один элемент. Получатель отвечает на ваше сообщение, выбирая один из элементов в ранее отправленном вами интерактивном сообщении.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

  • Поле context содержит информацию о ранее отправленном вами интерактивном сообщении.
    • context.from — это WhatsApp ID (номер телефона без префикса «+») отправителя интерактивного сообщения.
    • context.id — это исходный ID сообщения на платформе WhatsApp, начинающийся с wamid..

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

В этом случае ваша конечная точка Webhook получила входящее интерактивное сообщение с ответом кнопкой (Interactive Button Reply):
  • Поле interactive содержит ответ кнопкой, которую нажал пользователь в ранее отправленном вами интерактивном сообщении.
  • Поле context содержит информацию об интерактивном сообщении, ранее отправленном вами пользователю.
example-inboundmessage-buttonreply.png

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

  • Поле context содержит информацию о ранее отправленном вами интерактивном сообщении.
    • context.from — это WhatsApp ID (номер телефона без префикса «+») отправителя интерактивного сообщения.
    • context.id — это исходный ID сообщения на платформе WhatsApp, начинающийся с wamid..

Входящее интерактивное сообщение с ответом из Flow

После завершения flow в чат WhatsApp будет отправлено ответное сообщение. Вы получите его так же, как и все остальные сообщения от пользователя — через Webhook сообщений. Поле response_json будет содержать данные, специфичные для flow.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

  • 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. previous_user_id указывает на предыдущий BSUID, если Meta предоставляет его.
  • parent_user_id и previous_parent_user_id — это необязательные родительские идентификаторы Parent BSUID, которые включаются только тогда, когда функция включена и данные предоставлены Meta. Сохраняйте исходные имена полей в snake_case внутри system.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, дедуплицируйте его по id и передавайте медленные или потенциально сбойные задачи в асинхронный обработчик.

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

Вы также можете получить входящее системное сообщение, в котором для system.type установлено значение user_changed_user_id. Номер телефона пользователя может остаться неизменным или быть недоступным. Используйте system.previous_user_id и system.user_id, чтобы связать предыдущий и новый BSUID, если переданы оба значения. Поля Parent BSUID являются необязательными.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

В этом примере from и system.wa_id опущены, так как номер телефона недоступен. Если передан параметр wa_id, он содержит номер телефона без ведущего символа +; не предполагайте автоматически, что он отличается от прежнего номера. Сохраняйте существующий номер телефона, если событие не содержит заменяющего значения.

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

В этом случае ваша конечная точка webhook получила входящее сообщение с заказом, когда клиент добавляет один или несколько товаров в корзину и оформляет заказ:
  • Содержит информацию о заказанном товаре.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, дедуплицируйте его по id и передавайте медленные или потенциально сбойные задачи в асинхронный обработчик.

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

В этом случае ваша конечная точка webhook получила входящее текстовое сообщение, когда клиент запрашивает информацию о товаре:
  • Содержит информацию о товаре.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

  • Сообщение с запросом информации о товаре принимается, когда пользователь запрашивает дополнительные сведения о конкретном товаре. Оно может быть получено в двух сценариях:
    • Когда клиент отвечает на сообщения с одним или несколькими товарами.
    • Когда клиент открывает каталог компании через другую точку входа, переходит на страницу сведений о товаре и нажимает кнопку «Написать компании об этом товаре».

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

Вы можете получать уведомления через webhook каждый раз, когда пользователь WhatsApp впервые открывает чат с вами. Это полезно, если вы хотите отправлять таким пользователям специальное приветственное сообщение собственного дизайна. Если эта функция включена и пользователь открывает чат (как правило, нажимая универсальную ссылку — ссылки формата wa.me или api.whatsapp.com ), клиент WhatsApp проверяет наличие существующей переписки между пользователем и номером телефона вашей компании. Если переписка отсутствует, клиент активирует webhook request_welcome. Затем вы можете отправить пользователю собственное приветственное сообщение. example-inboundmessage-welcomemessage

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

  • Чтобы включить эту функцию для номера телефона, перейдите в Meta WhatsApp Manager > Номера телефонов > Настройки > Автоматизация.
  • Чтобы протестировать сообщение request_welcome, если у вас уже есть существующий чат с номером телефона компании, сначала необходимо удалить этот чат.
  • Эта функция только инициирует входящее сообщение request_welcome и не отправляет никаких автоматических ответов. Отправлять ли приветственное сообщение, решаете вы.

Входящее SMS

Используйте sms.inbound.received, когда пользователь отвечает на ваше SMS.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

Считайте ответ из smsInbound.text. from — это номер телефона пользователя, to — ваш зарегистрированный Sender ID, а sendTime — время отправки сообщения. Не обрабатывайте это событие как whatsappInboundMessage.

Маркетинговые предпочтения WhatsApp

Используйте whatsapp.user.preferences, когда пользователь WhatsApp отключает или возобновляет получение маркетинговых сообщений.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

Считайте category и value из whatsappUserPreference; в этом примере зафиксирован запрос на прекращение получения маркетинговых сообщений. Используйте бизнес-идентификаторы и предоставленные идентификаторы клиентов для сопоставления предпочтения. parentUserId опускается, если родительские BSUID не включены. Сохраните detail как пояснительный текст и сохраните переданный timestamp. Это специальное событие предпочтений, а не входящее сообщение чата или полезная нагрузка contact.unsubscribe.created.

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

Подпишитесь на messenger.inbound_message.received для обычных личных текстовых сообщений. Проверьте заголовок YCloud-Signature перед подтверждением события. Повторная попытка доставки сохраняет Event.id; повторное создание события из того же исходного факта может сгенерировать новый Event.id. Сопоставляйте повторяющиеся входящие сообщения по messengerInboundMessage.id.

Запрос

Ответ

Пояснение

PSID клиента — from, а ID страницы Facebook — to. Сохраняйте текст в точности, включая пробелы. sendTime — сохраненное время исходного события; createTime — время локального сохранения. Это событие передает только обычные текстовые сообщения. Повторная доставка из источника может создать еще одно событие для того же сохраненного ID сообщения.

Редактирование входящего текстового сообщения Messenger

Подпишитесь на messenger.inbound_message.updated, чтобы получать актуальный текст существующего входящего сообщения. Проверьте YCloud-Signature перед обработкой полезной нагрузки.

Запрос

Ответ

Пояснение

Сохраняйте те же id и metaMessageId сообщения при обновлении вашей записи. Новые text.body, совокупное editCount и editTime описывают сохраненное изменение. sendTime и createTime сообщения сохраняют свои исходные значения; createTime события — это время редактирования. В неотредактированных сообщениях поля редактирования опускаются. Обновляются только существующие входящие сообщения; отсутствующие оригиналы и устаревшие версии правок не восстанавливаются. Повторные попытки доставки сохраняют ID события, но повторная обработка источником может создать новый ID события. Используйте ID сообщения и счетчик правок для обработки дубликатов и упорядочивания.