Полный каталог, сформированный на основе схемы, см. в разделе все примеры.
Что это такое
Обработка входящих сообщений 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:- Содержит обычный текст.
- Содержит информацию о рекламе.
Запрос
Ответ
Подтвердите доставку после надежного сохранения события.Пояснение
- Поле
referralсодержит сведения о рекламе. См. также раздел Реклама с переходом в 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содержит информацию об интерактивном сообщении, которое вы ранее отправили пользователю.
Запрос
Ответ
Подтвердите доставку после надежного сохранения события.Пояснение
- Поле
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 проверяет наличие существующей цепочки сообщений между пользователем и номером вашей компании. Если переписки нет, клиент инициирует 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 сообщения и счетчик правок для обработки дубликатов и упорядочивания.
