Полный каталог на основе схемы приведен в разделе все примеры.
Что это такое
Обработка входящих сообщений WhatsApp, Messenger и SMS, а также маркетинговых предпочтений WhatsApp.Перед началом работы
- Создайте общедоступную конечную точку HTTPS в своем приложении.
- Настройте конечную точку Webhook YCloud для необходимых типов событий.
- Безопасно сохраните секретный ключ подписи конечной точки.
- Сделайте обработку событий идемпотентной.
Как это работает
YCloud отправляет запрос HTTPPOST при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ 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
Подтвердите доставку после надежного принятия события.Пояснение
- Поле
referralсодержит информацию о рекламе. См. также Ads that Click to WhatsApp.
Входящее сообщение с изображением
В этом случае ваша конечная точка 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содержит информацию об интерактивном сообщении, ранее отправленном вами пользователю.
Запрос
Ответ
Подтвердите доставку после надежного сохранения события.Пояснение
- Поле
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 проверяет наличие существующей переписки между пользователем и номером телефона вашей компании. Если переписка отсутствует, клиент активирует webhookrequest_welcome. Затем вы можете отправить пользователю собственное приветственное сообщение.
Запрос
Ответ
Подтвердите доставку после надежного сохранения события.Пояснение
- Чтобы включить эту функцию для номера телефона, перейдите в 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 сообщения и счетчик правок для обработки дубликатов и упорядочивания.
