whatsapp.inbound_message.received

Используйте whatsapp.inbound_message.received для обработки этого события на вашей конечной точке Webhook.

Триггеры

Срабатывает при получении входящего сообщения WhatsApp. Подпишитесь на whatsapp.inbound_message.received, когда настраиваете свою конечную точку Webhook. Используйте type сообщения для выбора объекта его содержимого. Мультимедиа, интерактивные ответы, местоположение, контакты и системные уведомления имеют разные поля. В приведенных ниже примерах показаны эти варианты.

Синтаксис

YCloud отправляет HTTP-запрос POST на настроенный вами Webhook URL. Следующая структура демонстрирует один из вариантов полезной нагрузки. Значения в угловых скобках являются плейсхолдерами; их типы перечислены в разделе Параметры. Необязательные поля и другие варианты описаны ниже.

{
  "id": "<ID>",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappInboundMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "to": "<TO>",
    "sendTime": "<SEND_TIME>",
    "type": "<TYPE>",
    "system": {
      "type": "<TYPE>",
      "previous_user_id": "<PREVIOUS_USER_ID>",
      "previous_parent_user_id": "<PREVIOUS_PARENT_USER_ID>"
    }
  }
}

Параметры

Проверьте HTTP-заголовок YCloud-Signature перед обработкой тела JSON. См. раздел проверка подписи.

Конверт события

Параметр	Тип	Обязательный	Описание
`id`	string	Да	Уникальный идентификатор события. Минимальная длина: `6`. Максимальная длина: `128`.
`type`	string	Да	Всегда `whatsapp.inbound_message.received`.
`apiVersion`	string	Да	Версия API, используемая для формирования этого события.
`createTime`	string (date-time)	Да	Время создания этого события в формате RFC 3339. Например, `2022-06-01T12:00:00.000Z`.

Полезная нагрузка события

Параметр	Тип	Обязательный	Описание
`whatsappInboundMessage`	object	Нет	Специфичная для события полезная нагрузка `whatsappInboundMessage`.

Четыре общих поля конверта обязательны. Поля полезной нагрузки зависят от варианта события. В таблице каждого объекта статус Обязательный действует, если присутствует его родительский объект. Необязательные поля могут отсутствовать; наличие примера не делает поле обязательным.

whatsappInboundMessage

Параметр	Тип	Обязательный	Описание
`id`	string	Да	Уникальный идентификатор объекта.
`wamid`	string	Нет	Исходный идентификатор сообщения на платформе WhatsApp.
`wabaId`	string	Нет	Идентификатор WhatsApp Business Account.
`from`	string	Нет	Номер телефона клиента, отправившего сообщение компании, в формате E.164.
`fromUserId`	string	Нет	Идентификатор пользователя клиента в области действия WhatsApp Business (BSUID).
`fromParentUserId`	string	Нет	Родительский идентификатор пользователя клиента в области действия WhatsApp Business.
`customerProfile`	object	Нет	Данные профиля клиента.
`to`	string	Нет	Номер телефона получателя в формате E.164.
`sendTime`	string (date-time)	Нет	Время отправки этого сообщения в формате RFC 3339. Например, `2022-06-01T12:00:00.000Z`.
`type`	string	Нет	Тип входящего сообщения WhatsApp. См. также объект сообщений Webhook WhatsApp. Значения: `text`, `image`, `video`, `audio`, `document`, `sticker`, `contacts`, `location`, `interactive`, `button`, `reaction`, `request_welcome`, `order`, `system`, `unsupported`.
`text`	object	Нет	Если уведомление относится к текстовому сообщению, объект text содержит тело этого текстового сообщения.
`image`	object	Нет	При получении сообщения с медиафайлом (`image` \| `document` \| `audio` \| `video` \| `sticker`) клиент WhatsApp Business API скачивает этот медиафайл. После скачивания медиафайла на ваш Webhook отправляется уведомление. Это сообщение содержит информацию, идентифицирующую медиаобъект и позволяющую найти и скачать его.
`video`	object	Нет	При получении сообщения с медиафайлом (`image` \| `document` \| `audio` \| `video` \| `sticker`) клиент WhatsApp Business API скачивает этот медиафайл. После скачивания медиафайла на ваш Webhook отправляется уведомление. Это сообщение содержит информацию, идентифицирующую медиаобъект и позволяющую найти и скачать его.
`audio`	object	Нет	При получении сообщения с медиафайлом (`image` \| `document` \| `audio` \| `video` \| `sticker`) клиент WhatsApp Business API скачивает этот медиафайл. После скачивания медиафайла на ваш Webhook отправляется уведомление. Это сообщение содержит информацию, идентифицирующую медиаобъект и позволяющую найти и скачать его.
`document`	object	Нет	При получении сообщения с медиафайлом (`image` \| `document` \| `audio` \| `video` \| `sticker`) клиент WhatsApp Business API скачивает этот медиафайл. После скачивания медиафайла на ваш Webhook отправляется уведомление. Это сообщение содержит информацию, идентифицирующую медиаобъект и позволяющую найти и скачать его.
`sticker`	object	Нет	При получении сообщения с медиафайлом (`image` \| `document` \| `audio` \| `video` \| `sticker`) клиент WhatsApp Business API скачивает этот медиафайл. После скачивания медиафайла на ваш Webhook отправляется уведомление. Это сообщение содержит информацию, идентифицирующую медиаобъект и позволяющую найти и скачать его.
`interactive`	object	Нет	Когда клиент взаимодействует с вашим сообщением, этот объект включается в объект сообщения.
`location`	object	Нет	Когда вы получаете уведомление о статическом местоположении пользователя, объект location предоставляет подробные сведения об этом местоположении.
`button`	object	Нет	Когда поле типа сообщения имеет значение `button`, этот объект включается в объект сообщения.
`contacts`	object[]	Нет	Элементы массива описаны ниже.
`reaction`	object	Нет	Когда пользователь реагирует на сообщения с помощью эмодзи, типу сообщения присваивается значение `reaction`, и включается это поле.
`order`	object	Нет	Когда клиент оформляет заказ, типу сообщения присваивается значение `order`, и включается это поле.
`system`	object	Нет	Когда тип сообщения имеет значение `system`, включается это поле. Этот объект описывает смену номера телефона пользователя, изменение BSUID или возможное изменение учетных данных пользователя в WhatsApp.
`errors`	object[]	Нет	Элементы массива описаны ниже.
`context`	object	Нет	Контекст сообщения.
`referral`	object	Нет	Когда пользователь отправляет сообщение компании с помощью кнопок призыва к действию в объявлениях с переходом в WhatsApp или кнопок призыва к действию на Странице Facebook, это поле включается в качестве вложения.
`groupId`	string	Нет	Идентификатор группы WhatsApp. Это поле включается, когда входящее сообщение отправлено в группе WhatsApp.

Параметры вложенных объектов

Разверните поле, чтобы просмотреть его вложенные параметры.

whatsappInboundMessage.customerProfile

Параметр	Тип	Обязательный	Описание
`name`	string	Нет	Имя аккаунта WhatsApp.
`username`	string	Нет	Имя пользователя WhatsApp.

whatsappInboundMessage.text

Параметр	Тип	Обязательный	Описание
`body`	string	Нет	Текст сообщения.

whatsappInboundMessage.image

Параметр	Тип	Обязательный	Описание
`id`	string	Нет	Идентификатор медиафайла. Может использоваться для удаления медиафайла, если он сохранен локально на стороне клиента.
`link`	string	Нет	URL-адрес для скачивания медиафайла. Обратите внимание, что для удобства пользователя эта ссылка может быть доступна напрямую в течение нескольких минут, однако вам всегда следует указывать заголовок `X-API-Key`, чтобы скачивать этот файл в течение месяца.
`caption`	string	Нет	Предоставленная подпись к медиафайлу. Присутствует, только если указана.
`filename`	string	Нет	Имя файла на устройстве отправителя. Будет присутствовать только в медиасообщениях типа `document`.
`metadata`	object	Нет	Метаданные, относящиеся к медиафайлам `sticker`.
`mime_type`	string	Нет	MIME-тип медиафайла.
`sha256`	string	Нет	Контрольная сумма.

whatsappInboundMessage.video

Параметр	Тип	Обязательный	Описание
`id`	string	Нет	Идентификатор медиафайла. Может использоваться для удаления медиафайла, если он сохранен локально на стороне клиента.
`link`	string	Нет	URL-адрес для скачивания медиафайла. Обратите внимание, что для удобства пользователя эта ссылка может быть доступна напрямую в течение нескольких минут, однако вам всегда следует указывать заголовок `X-API-Key`, чтобы скачивать этот файл в течение месяца.
`caption`	string	Нет	Предоставленная подпись к медиафайлу. Присутствует, только если указана.
`filename`	string	Нет	Имя файла на устройстве отправителя. Будет присутствовать только в медиасообщениях типа `document`.
`metadata`	object	Нет	Метаданные, относящиеся к медиафайлам `sticker`.
`mime_type`	string	Нет	MIME-тип медиафайла.
`sha256`	string	Нет	Контрольная сумма.

whatsappInboundMessage.audio

Параметр	Тип	Обязательный	Описание
`id`	string	Нет	Идентификатор медиафайла. Может использоваться для удаления медиафайла, если он сохранен локально на стороне клиента.
`link`	string	Нет	URL-адрес для скачивания медиафайла. Обратите внимание, что для удобства пользователя эта ссылка может быть доступна напрямую в течение нескольких минут, однако вам всегда следует указывать заголовок `X-API-Key`, чтобы скачивать этот файл в течение месяца.
`caption`	string	Нет	Предоставленная подпись к медиафайлу. Присутствует, только если указана.
`filename`	string	Нет	Имя файла на устройстве отправителя. Будет присутствовать только в медиасообщениях типа `document`.
`metadata`	object	Нет	Метаданные, относящиеся к медиафайлам `sticker`.
`mime_type`	string	Нет	MIME-тип медиафайла.
`sha256`	string	Нет	Контрольная сумма.

whatsappInboundMessage.document

Параметр	Тип	Обязательный	Описание
`id`	string	Нет	Идентификатор медиафайла. Может использоваться для удаления медиафайла, если он сохранен локально на стороне клиента.
`link`	string	Нет	URL-адрес для скачивания медиафайла. Обратите внимание, что для удобства пользователя эта ссылка может быть доступна напрямую в течение нескольких минут, однако вам всегда следует указывать заголовок `X-API-Key`, чтобы скачивать этот файл в течение месяца.
`caption`	string	Нет	Предоставленная подпись к медиафайлу. Присутствует, только если указана.
`filename`	string	Нет	Имя файла на устройстве отправителя. Присутствует только в медиасообщениях `document`.
`metadata`	object	Нет	Метаданные, относящиеся к медиафайлам `sticker`.
`mime_type`	string	Нет	MIME-тип медиафайла.
`sha256`	string	Нет	Контрольная сумма.

whatsappInboundMessage.sticker

Параметр	Тип	Обязательный	Описание
`id`	string	Нет	Идентификатор медиафайла. Может использоваться для удаления медиафайла, если он сохранен локально на клиенте.
`link`	string	Нет	URL для скачивания медиафайла. Обратите внимание, что для удобства пользователя к этой ссылке можно обращаться напрямую в течение нескольких минут, однако для скачивания этого файла в течение месяца всегда следует передавать заголовок `X-API-Key`.
`caption`	string	Нет	Предоставленная подпись к медиафайлу. Присутствует, только если указана.
`filename`	string	Нет	Имя файла на устройстве отправителя. Присутствует только в медиасообщениях `document`.
`metadata`	object	Нет	Метаданные, относящиеся к медиафайлам `sticker`.
`mime_type`	string	Нет	MIME-тип медиафайла.
`sha256`	string	Нет	Контрольная сумма.

whatsappInboundMessage.interactive

Параметр	Тип	Обязательный	Описание
`type`	string	Нет	Тип полученного интерактивного сообщения. `button_reply`: отправляется, когда клиент нажимает кнопку. `list_reply`: отправляется, когда клиент выбирает элемент из списка. `nfm_reply`: отправляется, когда клиент отвечает на WhatsApp Flow (Next Feature Messaging). `call_permission_reply`: отправляется, когда клиент отвечает на запрос разрешения на звонок.
`button_reply`	object	Нет	Отправляется, когда клиент нажимает кнопку. Возвращается, когда `type` имеет значение `button_reply`.
`list_reply`	object	Нет	Отправляется, когда клиент выбирает элемент из списка. Возвращается, когда `type` имеет значение `list_reply`.
`nfm_reply`	object	Нет	Отправляется, когда клиент отвечает на WhatsApp Flow (Next Feature Messaging). Возвращается, когда `type` имеет значение `nfm_reply`.
`call_permission_reply`	object	Нет	Отправляется, когда клиент отвечает на запрос разрешения на звонок. Возвращается, когда `type` имеет значение `call_permission_reply`. Это происходит, когда WhatsApp предлагает пользователям предоставить разрешения на обратный звонок после того, как они позвонили в вашу компанию.

whatsappInboundMessage.interactive.button_reply

Параметр	Тип	Обязательный	Описание
`id`	string	Нет	Уникальный идентификатор нажатой кнопки.
`title`	string	Нет	Заголовок кнопки.

whatsappInboundMessage.interactive.list_reply

Параметр	Тип	Обязательный	Описание
`id`	string	Нет	Уникальный идентификатор выбранного элемента списка.
`title`	string	Нет	Заголовок выбранного элемента списка.
`description`	string	Нет	Описание выбранной строки.

whatsappInboundMessage.interactive.nfm_reply

Параметр	Тип	Обязательный	Описание
`name`	string	Нет	Название flow или формы, на которую отправляется ответ.
`response_json`	string	Нет	Строка JSON, содержащая ответы пользователя на flow. Содержит значения полей формы и flow token.
`body`	string	Нет	Текст тела сообщения с ответом на flow.

whatsappInboundMessage.interactive.call_permission_reply

Параметр	Тип	Обязательный	Описание
`response`	string	Нет	Ответ клиента на запрос разрешения на звонок. `accept`: Пользователь предоставил компании разрешение на обратный звонок `reject`: Пользователь отклонил разрешение компании на обратный звонок
`expiration_timestamp`	integer (int64)	Нет	Временная метка (в секундах), когда истекает срок действия разрешения на звонок. Присутствует только тогда, когда ответ — “accept”, а is_permanent имеет значение false.
`is_permanent`	boolean	Нет	Является ли разрешение постоянным или временным. `true`: Постоянное разрешение (без срока действия) `false`: Временное разрешение (истекает в указанный в expiration_timestamp момент времени)

whatsappInboundMessage.location

Параметр	Тип	Обязательный	Описание
`latitude`	number (double)	Нет	Широта отправляемого местоположения.
`longitude`	number (double)	Нет	Долгота отправляемого местоположения.
`address`	string	Нет	Адрес местоположения.
`name`	string	Нет	Название местоположения.
`url`	string	Нет	URL веб-сайта, с которого пользователь загрузил информацию о местоположении.

whatsappInboundMessage.button

Параметр	Тип	Обязательный	Описание
`payload`	string	Нет	Полезная нагрузка (payload) кнопки, настроенной компанией, которую клиент нажал в рамках интерактивного сообщения.
`text`	string	Нет	Текст кнопки.

whatsappInboundMessage.contacts[]

Параметр	Тип	Обязательный	Описание
`addresses`	object[]	Нет	Элементы массива описаны ниже.
`birthday`	string	Нет	Строка в формате `YYYY-MM-DD`.
`emails`	object[]	Нет	Элементы массива описаны ниже.
`name`	object	Да	Полное имя контакта, отформатированное как объект name.
`org`	object	Нет	Информация об организации контакта, отформатированная как объект org.
`phones`	object[]	Нет	Телефонный номер(а) контакта, отформатированный как объект phone.
`urls`	object[]	Нет	URL-адрес(а) контакта, отформатированный как объект urls.
`vcard`	string	Нет	Необязательная визитная карточка vCard, переданная вместе с полезной нагрузкой общего контакта.
`origin`	string	Нет	Имеет значение `contact_request`, когда пользователь поделился контактом в ответ на сообщение с запросом контактной информации.

whatsappInboundMessage.contacts[].addresses[]

Параметр	Тип	Обязательный	Описание
`street`	string	Нет	Номер дома и название улицы.
`city`	string	Нет	Название города.
`state`	string	Нет	Аббревиатура штата/региона.
`zip`	string	Нет	Почтовый индекс.
`country`	string	Нет	Полное название страны.
`country_code`	string	Нет	Двухбуквенный код (сокращение) страны.
`type`	string	Нет	Стандартные значения: `HOME` и `WORK`.

whatsappInboundMessage.contacts[].emails[]

Параметр	Тип	Обязательный	Описание
`email`	string	Нет	Адрес электронной почты.
`type`	string	Нет	Стандартные значения: `HOME` и `WORK`.

whatsappInboundMessage.contacts[].name

Параметр	Тип	Обязательный	Описание
`formatted_name`	string	Да	Полное имя в привычном представлении.
`first_name`	string	Нет	Имя.
`last_name`	string	Нет	Фамилия.
`middle_name`	string	Нет	Отчество или второе имя.
`suffix`	string	Нет	Суффикс имени.
`prefix`	string	Нет	Префикс имени.

whatsappInboundMessage.contacts[].org

Параметр	Тип	Обязательный	Описание
`company`	string	Нет	Название компании контакта.
`department`	string	Нет	Название отдела контакта.
`title`	string	Нет	Должность контакта.

whatsappInboundMessage.contacts[].phones[]

Параметр	Тип	Обязательный	Описание
`phone`	string	Нет	Автоматически заполняется значением `wa_id` в формате телефонного номера.
`type`	string	Нет	Стандартные значения: `CELL`, `MAIN`, `IPHONE`, `HOME` и `WORK`.
`wa_id`	string	Нет	WhatsApp ID.

whatsappInboundMessage.contacts[].urls[]

Параметр	Тип	Обязательный	Описание
`url`	string	Нет	URL.
`type`	string	Нет	Стандартные значения: `HOME` и `WORK`.

whatsappInboundMessage.reaction

Параметр	Тип	Обязательный	Описание
`message_id`	string	Да	Указывает `wamid` полученного сообщения, на которое была оставлена реакция.
`emoji`	string	Нет	Обязательно при отправке сообщения `reaction`. Установите значение `""`, если хотите удалить эмодзи. Необязательно при получении сообщения от пользователя. Это поле передается, если пользователь отреагировал на сообщение с помощью эмодзи. В противном случае оно указывает, что пользователь удалил эмодзи.

whatsappInboundMessage.order

Параметр	Тип	Обязательный	Описание
`catalog_id`	string	Нет	Идентификатор каталога.
`product_items`	object[]	Нет	Элементы массива описаны ниже.
`text`	string	Нет	Текстовое сообщение, отправленное вместе с заказом.

whatsappInboundMessage.order.product_items[]

Параметр	Тип	Обязательный	Описание
`product_retailer_id`	string	Нет	Идентификатор артикула (SKU) товара.
`quantity`	integer (int32)	Нет	Количество единиц товара.
`item_price`	number (double)	Нет	Цена за единицу товара.
`currency`	string	Нет	Валюта цены. Код валюты по ISO 4217.

whatsappInboundMessage.system

Параметр	Тип	Обязательный	Описание
`body`	string	Нет	Описывает событие системного сообщения. Поддерживаемые сценарии использования: Обновление номера телефона: когда пользователь переходит со старого номера на новый. Обновление идентификационных данных: когда личность пользователя изменилась.
`wa_id`	string	Нет	Номер телефона, предоставленный Meta, без начального `+`. При изменении BSUID он может остаться неизменным или быть опущен.
`user_id`	string	Нет	Новый business-scoped user ID, предоставленный Meta для изменения номера телефона или BSUID. Это поле сохраняет исходное имя в snake_case.
`parent_user_id`	string	Нет	Новый Parent BSUID при изменении номера телефона или BSUID, только если функция включена и значение предоставлено Meta. Это поле сохраняет исходное имя в snake_case.
`previous_user_id`	string	Нет	Предыдущий business-scoped user ID, предоставленный Meta.
`previous_parent_user_id`	string	Нет	Предыдущий Parent BSUID, только если функция включена и значение предоставлено Meta.
`type`	string	Нет	Поддерживаемые типы: `user_changed_user_id`: уведомление о том, что пользователь изменил свой BSUID. Номер телефона может остаться неизменным. `user_changed_number`: уведомление об изменении номера пользователем. `user_identity_changed`: уведомление об изменении идентификационных данных пользователя.
`user`	string	Нет	Добавляется в Webhook-события при обновлении идентификационных данных. Новый WhatsApp ID клиента.
`new_wa_id`	string	Нет	Добавляется в Webhook-события при обновлении номера телефона. Новый WhatsApp ID клиента.

whatsappInboundMessage.errors[]

Параметр	Тип	Обязательный	Описание
`code`	string	Нет	Код ошибки.
`title`	string	Нет	Заголовок ошибки.
`message`	string	Нет	Сообщение об ошибке.
`error_data`	object	Нет	Объект данных об ошибке со следующими свойствами: `details`: строка, описывающая причину ошибки. Пример: `Message type is currently not supported.`.

whatsappInboundMessage.context

Параметр	Тип	Обязательный	Описание
`forwarded`	boolean	Нет	Добавляется в Webhook-события, если сообщение было переслано. Имеет значение `true`, если полученное сообщение было переслано.
`frequently_forwarded`	boolean	Нет	Добавляется в Webhook-события, если сообщение часто пересылалось. Имеет значение `true`, если полученное сообщение было переслано более пяти раз.
`from`	string	Нет	Добавляется в Webhook-события, если сообщение является входящим ответом на отправленное сообщение. WhatsApp ID (номер телефона без префикса «+») отправителя отправленного сообщения.
`id`	string	Нет	Необязательно. Идентификатор `wamid` отправленного сообщения для входящего ответа. `wamid` — это исходный идентификатор сообщения на платформе WhatsApp.
`referred_product`	object	Нет	Обязательно для сообщений с запросом о товаре. Указывает товар, о котором пользователь запрашивает информацию. См. также Sell Products & Services.

whatsappInboundMessage.context.referred_product

Параметр	Тип	Обязательный	Описание
`catalog_id`	string	Нет	Идентификатор каталога.
`product_retailer_id`	string	Нет	Идентификатор SKU товара.

whatsappInboundMessage.referral

Параметр	Тип	Обязательный	Описание
`source_url`	string	Нет	Задает URL, ведущий на рекламу или публикацию, по которой нажал пользователь. Открытие этого URL ведет к объявлению, которое просмотрел пользователь.
`source_type`	string	Нет	Указывает тип источника рекламы. Поддерживаемые значения: “ad” или “post”.
`source_id`	string	Нет	Задает идентификатор Meta ID для рекламы или публикации.
`headline`	string	Нет	Задает заголовок рекламы или публикации, которая сгенерировала сообщение.
`body`	string	Нет	Описание или основной текст из рекламы либо публикации, сгенерировавшей сообщение.
`media_type`	string	Нет	Медиафайл в объявлении или публикации, по которой нажал пользователь. Поддерживаемые значения: “image” или “video”.
`image_url`	string	Нет	Добавляется, если media_type имеет значение “image”. Содержит URL исходного изображения.
`video_url`	string	Нет	Добавляется, если media_type имеет значение “video”. Содержит URL видео.
`thumbnail_url`	string	Нет	Добавляется, если media_type имеет значение “video”. Содержит URL миниатюры видео, по которому был совершен клик.
`ctwa_clid`	string	Нет	Идентификатор клика, созданный Meta для рекламы с переходом в WhatsApp.

Пример

Следующий JSON представляет собой тело запроса, доставленное вашему получателю. Идентификаторы, номера телефонов и другие значения аккаунта приведены для наглядности.

Пользователь изменил BSUID без раскрытия номера телефона

{
  "id": "evt_system_user_id_changed_123",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "msg_system_user_id_changed_123",
    "wamid": "wamid.EXAMPLE_USER_ID_CHANGED",
    "wabaId": "whatsapp-business-account-id",
    "to": "+12025550123",
    "sendTime": "2026-10-10T08:00:00.000Z",
    "type": "system",
    "system": {
      "type": "user_changed_user_id",
      "previous_user_id": "US.13491208655302741918",
      "previous_parent_user_id": "US.ENT.11815799212886844830"
    }
  }
}

Пользователь изменил номер с предыдущими BSUID

{
  "id": "evt_system_number_changed_123",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "msg_system_number_changed_123",
    "wamid": "wamid.EXAMPLE_NUMBER_CHANGED",
    "wabaId": "whatsapp-business-account-id",
    "from": "+12025550124",
    "to": "+12025550123",
    "sendTime": "2026-10-10T08:00:00.000Z",
    "type": "system",
    "system": {
      "type": "user_changed_number",
      "previous_user_id": "US.13491208655302741918",
      "previous_parent_user_id": "US.ENT.11815799212886844830",
      "new_wa_id": "16315553333"
    }
  }
}

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

{
  "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"
  }
}

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

{
  "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": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

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

{
  "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"
    }
  }
}

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

{
  "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://example.com/sample",
      "caption": "Go for a walk.",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=",
      "mime_type": "image/jpeg"
    }
  }
}

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

{
  "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://example.com/sample",
      "caption": "Go for a walk.",
      "id": "919306472440541",
      "sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=",
      "mime_type": "video/mp4"
    }
  }
}

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

{
  "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://example.com/sample",
      "id": "712063723747110",
      "sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=",
      "mime_type": "audio/mpeg"
    }
  }
}

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

{
  "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://example.com/sample",
      "caption": "PDF example",
      "filename": "sample.pdf",
      "id": "948915536111569",
      "sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=",
      "mime_type": "application/pdf"
    }
  }
}

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

{
  "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://example.com/sample",
      "id": "729118992174848",
      "sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=",
      "mime_type": "image/webp"
    }
  }
}

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

{
  "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://example.com/sample"
    }
  }
}

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

{
  "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": "recipient@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"
          }
        ],
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}

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

{
  "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": "👍"
    }
  }
}

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

{
  "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": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

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

{
  "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": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

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

{
  "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": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

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

{
  "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": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

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

{
  "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": 2,
          "item_price": 12.5,
          "currency": "price-currency"
        }
      ],
      "text": "text-message-sent-along-with-the-order"
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
    }
  }
}

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

{
  "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"
      }
    }
  }
}

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

{
  "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"
  }
}

После проверки подписи и надежного принятия события верните ответ 2xx. Длительные операции обрабатывайте асинхронно.

HTTP/1.1 200 OK

Пошаговые сценарии см. в разделе аннотированные примеры.

Начало работы

Руководства

Конечные точки

Webhook reference

whatsapp.inbound_message.received

Триггеры

Синтаксис

Параметры

Конверт события

Полезная нагрузка события

whatsappInboundMessage

Параметры вложенных объектов

Пример

​Триггеры

​Синтаксис

​Параметры

​Конверт события

​Полезная нагрузка события

​whatsappInboundMessage

Параметры вложенных объектов

​Пример

Триггеры

Синтаксис

Параметры

Конверт события

Полезная нагрузка события

whatsappInboundMessage

Пример