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

Что это такое

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

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

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

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

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

Запрос

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

Ответ

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

  • Поле context содержит информацию о ранее отправленном вами интерактивном сообщении.
    • context.from — это WhatsApp ID (номер телефона без префикса «+») отправителя интерактивного сообщения.
    • context.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 template message и Interactive Flow message.

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

В этом случае ваша конечная точка вебхука получила входящее системное сообщение:
  • Параметр type имеет значение system, а system.type — значение user_changed_number.
  • Пользователь меняет свой номер телефона в WhatsApp, и wa_id является новым WhatsApp ID (номером телефона без префикса +).
  • user_id — это новый BSUID. Параметр parent_user_id включается только тогда, когда включены родительские BSUID.

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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