Полезная нагрузка входящего веб-хука WhatsApp | Документация для разработчиков
Полезная нагрузка входящего веб-перехватчика WhatsApp
Экземпляр для программы магистратуры (LLM)
Версия
Схемы для входящих уведомлений веб-перехватчика WhatsApp.
Определяет структуру полезной нагрузки для сообщений, обновлений статуса и взаимодействий с пользователем
Отправлено пользователями WhatsApp компаниям через веб-хуки.
Базовый URL
Конечные точки
ПОЧТА |
POST /whatsapp/webhooks
Конечная точка для приема данных веб-хуков для различных типов входящих сообщений WhatsApp.
Синтаксис запроса
POST /whatsapp/webhooks
Выберите язык
curl --request POST \ --url 'https://graph.facebook.com/whatsapp/webhooks' \ --header 'Authorization: Bearer<Token> ' \ --header 'Content-Type: application/json' \ --data '{ "object": "whatsapp_business_account", "entry": [ { "id": "419561257915477", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Sheena Nelson" }, "wa_id": "16505551234" } ], "messages": [ { "from": "16505551234", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=", "timestamp": "1749416383", "type": "text", "text": { "body": "Есть ли он в другом цвете?" } } ] }, "field": "messages" } ] } ] }'Текст запросаНеобходимый
Полезная нагрузка веб-хука, содержащая входящие сообщения WhatsApp.
Тип содержимого: application/json
Схема: WebhookPayload
Показать дочерние атрибуты
WebhookPayload
строковый объект · обязательный
Для этих веб-хуков всегда используйте 'whatsapp_business_account'.
массив записей · обязательный
Показать дочерние атрибуты
запись[] Запись
Показать дочерние атрибуты
строковый идентификатор · обязательный
Идентификатор бизнес-аккаунта WhatsApp.
изменения массива Change · обязательный
Показать дочерние атрибуты
изменения[] Изменение
Показать дочерние атрибуты
Значение должно быть одним из следующих: IncomingMessageValueGeneral, IncomingMessageValueSystem, StatusMessageValue, GroupValue · обязательно
Показать дочерние атрибуты
ВходящееСообщениеЗначениеОбщее
Показать дочерние атрибуты
messaging_product string · required
Всегда пользуйтесь WhatsApp.
метаданные Метаданные · обязательны
Показать дочерние атрибуты
display_phone_number string · required
Номер телефона компании, отображаемый на экране.
phone_number_id строка · обязательный
Идентификатор номера служебного телефона.
контактов из ContactProfile · обязательно
Набор профилей контактов отправителя. Включен для всех входящих сообщений, не поступающих через систему.
Показать дочерние атрибуты
контакты[] Профиль контакта
Показать дочерние атрибуты
объект профиля · обязательный
Показать дочерние атрибуты
строка имени · обязательный
Имя пользователя WhatsApp, как оно отображается в его профиле в клиенте WhatsApp.
строка wa_id
Идентификатор пользователя WhatsApp. Обратите внимание, что идентификатор пользователя WhatsApp и номер телефона могут не всегда совпадать.
массив сообщений · обязательный
Массив объектов сообщений. Структура зависит от свойства 'type'.
Показать дочерние атрибуты
сообщения[] Входящее сообщение
Показать дочерние атрибуты
Текстовое сообщение
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "текст" · обязательный
текстовый объект · обязательный
Показать дочерние атрибуты
строка тела · обязательный
Текст сообщения.
объект контекста
Включается только при отправке сообщения через кнопку "Написать компании".
Показать дочерние атрибуты
из строки · обязательный
Номер телефона компании, отображаемый на экране.
строковый идентификатор · обязательный
Идентификатор сообщения WhatsApp, которое пользователь использовал для доступа к кнопке «Сообщение для бизнеса».
объект referred_product · обязательный
Показать дочерние атрибуты
catalog_id строка · обязательный
Идентификатор товара в каталоге.
product_retailer_id строка · обязательный
Идентификатор продукта.
объект направления
Включено только при отправке сообщения через рекламное объявление Click to WhatsApp.
Показать дочерние атрибуты
строка source_url · обязательный
URL объявления.
строка source_id · обязательный
Идентификатор объявления.
source_type Один из "ad", "post" · обязательный
строка тела · обязательный
Основной текст объявления.
заголовок строки · обязательный
Заголовок объявления.
media_type Один из вариантов: "image", "video" · обязательный
строка image_url
Указано только для типа носителя изображения.
строка video_url
Указано только для видео media_type.
thumbnail_url string
Указано только для видео media_type.
строка ctwa_clid · обязательный
Идентификатор клика по объявлению.
объект welcome_message
Показать дочерние атрибуты
текстовая строка · обязательный
Приветственный текст объявления.
Реакция
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "реакция" · требуется
объект реакции · требуется
Показать дочерние атрибуты
message_id строка · обязательный
Идентификатор сообщения WhatsApp, на которое отреагировал пользователь WhatsApp.
строка эмодзи · обязательный
Эмодзи, отправленный пользователем WhatsApp в качестве реакции.
Аудиосообщение
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "аудио" · обязательный
аудиообъект
Показать дочерние атрибуты
mime_type строка · обязательный
MIME-тип медиафайла.
строка sha256 · обязательный
Хэш SHA-256 медиаактива.
строковый идентификатор · обязательный
Идентификатор медиафайла. Запрос GET по этому идентификатору может предоставить URL-адрес медиафайла.
логическое значение голоса · обязательно
Логическое значение, указывающее, является ли аудиозапись сделанной с помощью функции записи голоса в приложении WhatsApp (true) или нет (lave).
ДокументСообщение
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "документ" · обязательный
объект документа
Показать дочерние атрибуты
mime_type строка · обязательный
MIME-тип медиафайла.
строка sha256 · обязательный
Хэш SHA-256 медиаактива.
строковый идентификатор · обязательный
Идентификатор медиафайла. Запрос GET по этому идентификатору может предоставить URL-адрес медиафайла.
имя файла строка · обязательный
Имя файла медиафайла.
ImageMessage
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "изображение" · обязательный
объект изображения
Показать дочерние атрибуты
mime_type строка · обязательный
MIME-тип медиафайла.
строка sha256 · обязательный
Хэш SHA-256 медиаактива.
строковый идентификатор · обязательный
Идентификатор медиафайла. Запрос GET по этому идентификатору может предоставить URL-адрес медиафайла.
строка подписи
Текст подписи к медиафайлу.
НаклейкаСообщение
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "стикер" · обязательный
наклейка объект
Показать дочерние атрибуты
mime_type строка · обязательный
MIME-тип медиафайла.
строка sha256 · обязательный
Хэш SHA-256 медиаактива.
строковый идентификатор · обязательный
Идентификатор медиафайла. Запрос GET по этому идентификатору может предоставить URL-адрес медиафайла.
анимированный логический параметр · обязательный
Логическое значение, указывающее, является ли стикер анимированным (true) или нет (false).
Видеосообщение
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "видео" · обязательно
видеообъект
Показать дочерние атрибуты
mime_type строка · обязательный
MIME-тип медиафайла.
строка sha256 · обязательный
Хэш SHA-256 медиаактива.
строковый идентификатор · обязательный
Идентификатор медиафайла. Запрос GET по этому идентификатору может предоставить URL-адрес медиафайла.
строка подписи
Текст подписи к медиафайлу.
LocationMessage
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "местоположение" · обязательный
Объект местоположения · обязательный
Показать дочерние атрибуты
строка адреса · обязательный
Адрес местоположения.
широты (число с плавающей запятой) · обязательно
Широта местоположения.
долготы (число с плавающей запятой) · обязательно
Долгота местоположения.
строка имени · обязательный
Название местоположения.
строка URL
URL-адрес местоположения. Обычно указывается только для адресов предприятий.
ContactSharingMessage
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "контакты" · обязательный
контактов объекта ContactObject · обязательно
Массив объектов контактов. Многие свойства объектов контактов могут быть опущены, если пользователь WhatsApp решит не делиться ими или если его устройство не позволяет это сделать.
Показать дочерние атрибуты
контакт[] объект
Показать дочерние атрибуты
адреса массива объектов
Показать дочерние атрибуты
адреса[] объект
Показать дочерние атрибуты
городская струна
Город, указанный в контактном адресе
кантри струна
Страна, указанная в контактном адресе
Показать дочерние атрибуты
строка country_code
Код страны по стандарту ISO для контактного адреса
строка состояния
Штат, указанный в контактном адресе
уличная струна
Улица, указанная в контактном адресе
тип строка
Тип адреса, например, домашний или рабочий
зиплайн
Почтовый индекс в контактном адресе
дня рождения (дата)
Дата рождения контактного лица (ГГГГ-ММ-ДД).
массив объектов электронных писем
Показать дочерние атрибуты
emails[] объект
Показать дочерние атрибуты
email string (email)
Адрес электронной почты контакта
тип строка
Тип электронной почты, например, личная или рабочая
имя объекта
Показать дочерние атрибуты
formatted_name string · required
Отформатированное имя контакта
строка имени
Имя контактного лица
строка фамилии
Фамилия контактного лица
строка отчества
Второе имя контакта
суффиксная строка
Суффикс имени контакта
префиксная строка
Префикс имени контакта
объект организации
Показать дочерние атрибуты
строка компании
Название компании, в которой работает контактное лицо
строка отдела
Название отдела, в котором работает контактное лицо
строка заголовка
Должность контактного лица
телефонов объектов
Показать дочерние атрибуты
телефоны[] объект
Показать дочерние атрибуты
телефонная строка
Номер телефона контактного лица
строка wa_id
Номер WhatsApp контакта. Обратите внимание, что идентификатор пользователя WhatsApp и номер телефона могут не всегда совпадать.
тип строка
Тип телефонного номера. Например, мобильный, основной, iPhone, домашний, рабочий и т. д.
массив объектов urls
Показать дочерние атрибуты
объект urls[]
Показать дочерние атрибуты
URL (uri)
URL-адрес веб-сайта, связанного с контактом или его компанией
тип строка
Тип веб-сайта. Например, корпоративный, рабочий, личный, страница в Facebook, Instagram и т. д.
UnsupportedMessage
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип Один из "неподдерживаемый", "неизвестный" · обязательный
объект контекста · обязательный
Показать дочерние атрибуты
из строки · обязательный
Номер телефона компании, отображаемый на экране.
строковый идентификатор · обязательный
Идентификатор сообщения WhatsApp, содержащего кнопку, на которую нажал пользователь WhatsApp.
объект кнопки · обязательный
Показать дочерние атрибуты
строка полезной нагрузки · обязательный
Полезная нагрузка кнопки быстрого ответа.
текстовая строка · обязательный
Текст подписи кнопки быстрого ответа.
ButtonMessage
Интерактивное сообщениеОтвет
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "интерактивный" · обязательный
объект контекста · обязательный
Показать дочерние атрибуты
из строки · обязательный
Номер телефона компании, отображаемый на экране.
строковый идентификатор · обязательный
Идентификатор сообщения WhatsApp, содержащего интерактивный компонент, на который нажал пользователь.
интерактивный объект · обязательный
Показать дочерние атрибуты
Тип: Один из "list_reply", "button_reply" · обязательный
Тип интерактивного ответа (ответ в списке или ответ с помощью кнопки).
OrderMessage
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "заказ" · обязательный
объект заказа · обязательный
Показать дочерние атрибуты
catalog_id строка · обязательный
Идентификатор товара в каталоге.
текстовая строка · обязательный
Пустая строка.
массив объектов product_items · обязательный
Показать дочерние атрибуты
объект product_items[]
Показать дочерние атрибуты
product_retailer_id строка · обязательный
Идентификатор продукта.
количество целое число · требуемое
Количество товара.
item_price число (float) · обязательно
Цена за единицу товара.
строка валюты · обязательный
Код валюты каталога.
IncomingMessageValueSystem
Показать дочерние атрибуты
messaging_product string · required
Всегда пользуйтесь WhatsApp.
метаданные Метаданные · обязательны
Показать дочерние атрибуты
display_phone_number string · required
Номер телефона компании, отображаемый на экране.
phone_number_id строка · обязательный
Идентификатор номера служебного телефона.
массив сообщений · обязательный
Массив, содержащий только объекты сообщений типа 'system'.
Показать дочерние атрибуты
сообщения[] Системное сообщение
Показать дочерние атрибуты
из строки · обязательный
Номер телефона пользователя WhatsApp. Обратите внимание, что номер телефона и идентификатор пользователя WhatsApp не всегда могут совпадать.
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp.
строка метки времени · обязательно
Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
тип "система" · обязательный
системный объект · обязательный
Показать дочерние атрибуты
строка тела · обязательный
Описание изменения в системе (например, пользователь изменил номер).
строка wa_id
Новый идентификатор пользователя WhatsApp.
тип "user_changed_number" · обязательный
Тип системного сообщения.
неизвестно
StatusMessageValue
Показать дочерние атрибуты
messaging_product string · required
Всегда пользуйтесь WhatsApp.
метаданные Метаданные · обязательны
Показать дочерние атрибуты
display_phone_number string · required
Номер телефона компании, отображаемый на экране.
phone_number_id строка · обязательный
Идентификатор номера служебного телефона.
массив статусов · обязательный
Массив объектов состояния.
Показать дочерние атрибуты
статусы[] Статусы
Показать дочерние атрибуты
строковый идентификатор · обязательный
Уникальный идентификатор сообщения WhatsApp, с которым связан данный статус.
статус Один из "отправлено", "доставлено", "прочитано", "не удалось" · требуется
строка метки времени · обязательно
recipient_id string · required
Номер телефона получателя.
group_id строка
Идентификатор группы, если сообщение было отправлено группе.
разговор Разговор
Показать дочерние атрибуты
строка идентификатора
строка expiration_timestamp
происхождение разговораПроисхождение
Показать дочерние атрибуты
тип строка
ценообразование Цены
Показать дочерние атрибуты
оплачиваемый логический
pricing_model Один из "CBP", "PMP"
строка категории
ошибок StatusError
Показать дочерние атрибуты
ошибки[] StatusError
Показать дочерние атрибуты
код целое число
строка заголовка
строка сообщения
error_data ErrorData
Показать дочерние атрибуты
строка подробностей
href string
GroupValue
Показать дочерние атрибуты
messaging_product string · required
Всегда пользуйтесь WhatsApp.
метаданные Метаданные · обязательны
Показать дочерние атрибуты
display_phone_number string · required
Номер телефона компании, отображаемый на экране.
phone_number_id строка · обязательный
Идентификатор номера служебного телефона.
массив групп · обязательный
Массив групповых объектов.
Показать дочерние атрибуты
группы[] Группы
Показать дочерние атрибуты
метка времени целое число · обязательно
Unix-метка времени группового события
group_id строка · обязательный
Уникальный идентификатор для группы
Тип: Один из "group_create", "group_delete", "group_settings_update", "group_add_participants", "group_remove_participants" · обязательный
Тип группового мероприятия
request_id string · required
Уникальный идентификатор запроса
строка темы
Группа по предмету/название
строка описания
Описание группы
added_participants из GroupParticipant
Список участников, добавленных в группу
Показать дочерние атрибуты
добавленные_участники[] ГруппаУчастник
Показать дочерние атрибуты
входная строка
Введите номер телефона или идентификатор WhatsApp
строка wa_id
WhatsApp ID участника
removed_participants из GroupParticipant
Список участников, исключенных из группы
Показать дочерние атрибуты
удаленные участники[] Группа участников
Показать дочерние атрибуты
входная строка
Введите номер телефона или идентификатор WhatsApp
строка wa_id
WhatsApp ID участника
profile_picture GroupProfilePicture
Показать дочерние атрибуты
mime_type string
MIME-тип изображения профиля
строка sha256
Хэш SHA256 изображения профиля
Поле: Один из "messages", "group_lifecycle_update", "group_settings_update", "group_participant_update" · обязательное поле
В этом поле указывается, к какому объекту относится веб-перехватчик:
Сообщения: веб-хук связан с сообщениями от потребителя или со статусом сообщения, отправленного компанией потребителю.
group_lifecycle_update: веб-хук связан с созданием и удалением групп.
group_settings_update: веб-хук связан с обновлением настроек группы.
group_participant_update: веб-хук связан с присоединением и выходом участников из групп.
Ответы
Конечная точка для приема данных веб-хуков для различных типов входящих сообщений WhatsApp.
200
Веб-перехватчик успешно получен
Выберите язык
curl --request POST \ --url 'https://graph.facebook.com/whatsapp/webhooks' \ --header 'Authorization: Bearer<Token> ' \ --header 'Content-Type: application/json' \ --data '{ "object": "whatsapp_business_account", "entry": [ { "id": "419561257915477", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Sheena Nelson" }, "wa_id": "16505551234" } ], "messages": [ { "from": "16505551234", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=", "timestamp": "1749416383", "type": "text", "text": { "body": "Есть ли он в другом цвете?" } } ] }, "field": "messages" } ] } ] }'Аутентификация
Схема | Тип | Расположение |
bearerAuth | HTTP Bearer | Заголовок: Авторизация |
Примеры использования
bearerAuth:
Включите
Authorization: Bearer your-token-here в заголовки запроса.Глобальные требования к аутентификации
Для работы всех конечных точек требуется:
bearerAuth