Примеры полезной нагрузки уведомления Webhooks
Полученные сообщения
Текстовые сообщения
Вот пример текстового сообщения, которое вы получили от своего клиента:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"contacts": [
{
"profile": {
"name": "<WHATSAPP_USER_NAME>"
},
"wa_id": "<WHATSAPP_USER_ID>"
}
],
"messages": [
{
"from": "<WHATSAPP_USER_PHONE_NUMBER>",
"id": "<WHATSAPP_MESSAGE_ID>",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"text": {
"body": "<MESSAGE_BODY_TEXT>"
},
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}Сообщения с реакциями
Вот пример сообщения с реакцией от клиента. Вы не получите это уведомление Webhooks, если пользователь оставляет реакцию на сообщение старше 30 дней.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": PHONE_NUMBER
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"reaction": {
"message_id": "MESSAGE_ID",
"emoji": "EMOJI"
},
"type": "reaction"
}]
},
"field": "messages"
}]
}]
}
Примечание. Для сообщений с реакциями значение timestamp означает время, когда клиент отправил реакцию, а не время генерации уведомления Webhooks.
Сообщения с медиафайлами
При получении сообщения с медиафайлом платформа WhatsApp Business загружает этот файл. После этого на ваш Webhooks отправляется уведомление.
Оно содержит информацию, которая идентифицирует этот медиаобъект и позволяет найти и извлечь его. Чтобы извлечь медиафайл, используйте соответствующие конечные точки.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"type": "image",
"image": {
"caption": "CAPTION",
"mime_type": "image/jpeg",
"sha256": "IMAGE_HASH",
"id": "ID"
}
}]
},
"field": "messages"
}]
}]
}Когда вы получаете стикер, вам отправляется следующее уведомление:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "ID"
}
],
"messages": [
{
"from": "SENDER_PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"type": "sticker",
"sticker": {
"mime_type": "image/webp",
"sha256": "HASH",
"id": "ID"
}
}
]
},
"field": "messages"
}
]
}
]
}Неизвестные сообщения
Вы можете получить уведомление обратного вызова о неизвестном сообщении. Например, клиент может отправить вам неподдерживаемое сообщение (например, исчезающее). В таком случае мы уведомим клиента, что сообщение не поддерживается.
Вот пример неподдерживаемого сообщения от клиента.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"errors": [
{
"code": 131051,
"details": "Message type is not currently supported",
"title": "Unsupported message type"
}],
"type": "unknown"
}]
}
"field": "messages"
}],
}]
}Сообщения с местоположением
Вот пример сообщения с местоположением от клиента.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"location": {
"latitude": LOCATION_LATITUDE,
"longitude": LOCATION_LONGITUDE,
"name": LOCATION_NAME,
"address": LOCATION_ADDRESS,
}
}]
},
"field": "messages"
}]
}]
}Сообщения с контактами
Вот пример сообщения с контактами от клиента.
{
"object":"whatsapp_business_account",
"entry":[{
"id":"WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes":[{
"value":{
"messaging_product":"whatsapp",
"metadata": {
"display_phone_number":"PHONE_NUMBER",
"phone_number_id":"PHONE_NUMBER_ID"
},
"contacts": [{
"profile":{
"name":"NAME"
},
"wa_id":"WHATSAPP_ID"
}],
"messages":[{
"from":"PHONE_NUMBER",
"id":"wamid.ID",
"timestamp":"TIMESTAMP",
"contacts":[{
"addresses":[{
"city":"CONTACT_CITY",
"country":"CONTACT_COUNTRY",
"country_code":"CONTACT_COUNTRY_CODE",
"state":"CONTACT_STATE",
"street":"CONTACT_STREET",
"type":"HOME or WORK",
"zip":"CONTACT_ZIP"
}],
"birthday":"CONTACT_BIRTHDAY",
"emails":[{
"email":"CONTACT_EMAIL",
"type":"WORK or HOME"
}],
"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":"CONTACT_PHONE",
"wa_id":"CONTACT_WA_ID",
"type":"HOME or WORK>"
}],
"urls":[{
"url":"CONTACT_URL",
"type":"HOME or WORK"
}]
}]
}]
},
"field":"messages"
}]
}]
}Полученный обратный вызов при нажатии кнопки быстрого ответа
Когда ваш клиент нажимает кнопку быстрого ответа в интерактивном шаблоне сообщения, отправляется ответ. Вот пример формата обратного вызова.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"context": {
"from": PHONE_NUMBER,
"id": "wamid.ID"
},
"from": "16315551234",
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"type": "button",
"button": {
"text": "No",
"payload": "No-Button-Payload"
}
}]
},
"field": "messages"
}]
}]
}Полученный ответ из сообщения со списком
Если пользователь выбирает элемент в отправленном вами сообщении со списком, вы получите следующее уведомление Webhooks:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "PHONE_NUMBER_ID"
}
],
"messages": [
{
"from": PHONE_NUMBER_ID,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"interactive": {
"list_reply": {
"id": "list_reply_id",
"title": "list_reply_title",
"description": "list_reply_description"
},
"type": "list_reply"
},
"type": "interactive"
}
]
},
"field": "messages"
}
]
}
]
}Полученный ответ для кнопки ответа
Если пользователь нажимает отправленную вами кнопку ответа, вы получите следующее уведомление Webhooks:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": PHONE_NUMBER_ID,
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "PHONE_NUMBER_ID"
}
],
"messages": [
{
"from": PHONE_NUMBER_ID,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"interactive": {
"button_reply": {
"id": "unique-button-identifier-here",
"title": "button-text",
},
"type": "button_reply"
},
"type": "interactive"
}
]
},
"field": "messages"
}
]
}
]
}Полученное сообщение, инициированное нажатием рекламы в WhatsApp
Если переписка начинается, когда пользователь нажимает рекламу с кнопкой призыва к действию с переходом в WhatsApp, вы получите следующее уведомление Webhooks:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "ID"
}
],
"messages": [
{
"referral": {
"source_url": "AD_OR_POST_FB_URL",
"source_id": "ADID",
"source_type": "ad or post",
"headline": "AD_TITLE",
"body": "AD_DESCRIPTION",
"media_type": "image or video",
"image_url": "RAW_IMAGE_URL",
"video_url": "RAW_VIDEO_URL",
"thumbnail_url": "RAW_THUMBNAIL_URL",
"ctwa_clid": "CTWA_CLID"
},
"from": "SENDER_PHONE_NUMBERID",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"type": "text",
"text": {
"body": "BODY"
}
}
]
},
"field": "messages"
}
]
}
]
}Запросы информации о товаре
Когда клиент запрашивает дополнительную информацию о товаре, вы получаете соответствующее сообщение. Примеры:
- клиент отвечает на сообщение с одним или несколькими товарами;
- клиент переходит в каталог компании через другую точку входа, открывает страницу Информация о товаре и нажимает Спросить компанию о товаре.
Уведомление Webhooks о запросе информации о товаре выглядит так:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"contacts": [
{
"profile": {
"name": "NAME"
},
"wa_id": "PHONE_NUMBER_ID"
}
],
"messages": [
{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"text": {
"body": "MESSAGE_TEXT"
},
"context": {
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"referred_product": {
"catalog_id": "CATALOG_ID",
"product_retailer_id": "PRODUCT_ID"
}
},
"timestamp": "TIMESTAMP",
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}Сообщение с заказом
Уведомление Webhooks об оставленном заказе выглядит так:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "8856996819413533",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "16505553333",
"phone_number_id": "phone-number-id",
},
"contacts": [
{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}
],
"messages": [
{
"from": "16315551234",
"id": "wamid.ABGGFlCGg0cvAgo6cHbBhfK5760V",
"order": {
"catalog_id": "the-catalog_id",
"product_items": [
{
"product_retailer_id":"the-product-SKU-identifier",
"quantity":"number-of-item",
"item_price":"unitary-price-of-item",
"currency":"price-currency"
},
...
],
"text":"text-message-sent-along-with-the-order"
},
"context": {
"from": "16315551234",
"id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
},
"timestamp": "1603069091",
"type": "order"
}
]
},
"field": "messages"
}
]
}
]
}Уведомление об изменении номера пользователем
Если пользователь изменит свой номер телефона в WhatsApp, вы получите уведомление о системном сообщении:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"system": {
"body": "NAME changed from PHONE_NUMBER to PHONE_NUMBER",
"new_wa_id": NEW_PHONE_NUMBER,
"type": "user_changed_number"
},
"timestamp": TIMESTAMP,
"type": "system"
}]
},
"field": "messages"
}]
}]
}Обновление статуса сообщений
Модель платы за переписку изменилась. Чтобы узнать о работе новой модели платы за переписку, ознакомьтесь со статьей Расценки.
Кроме того, с 1 июля 2023 г. изменилась видимость metric_types. Подробнее см. в таблице аналитики переписок.
Платформа WhatsApp Business отправляет вам уведомления о статусе сообщений, передаваемых между вами и пользователями. Если сообщение отправлено успешно, вы получите уведомления о его отправке, доставке и прочтении. Очередность уведомлений в приложении может не соответствовать порядку наступления соответствующих событий. При необходимости проверяйте метку времени.
Статус: сообщение отправлено
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<WHATSAPP_MESSAGE_ID>",
"status": "sent",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"recipient_id": "<WHATSAPP_USER_ID>",
"conversation": {
"id": "<CONVERSATION_ID>",
"expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP>",
"origin": {
"type": "<CONVERSATION_CATEGORY>"
}
},
"pricing": {
"billable": <IS_BILLABLE?>,
"pricing_model": "CBP",
"category": "<CONVERSATION_CATEGORY>"
}
}
]
},
"field": "messages"
}
]
}
]
}Для переписок с бесплатными точками входа для origin.type и pricing.category установлено значение referral_conversion, а для pricing.billable установлено false.
Статус: сообщение доставлено
Если сообщение доставлено компании в переписке, начатой пользователем (если эта переписка не была начата с бесплатной точки входа), будет получено следующее уведомление:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<WHATSAPP_MESSAGE_ID>",
"status": "sent",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"recipient_id": "<WHATSAPP_USER_ID>",
"conversation": {
"id": "<CONVERSATION_ID>",
"origin": {
"type": "<CONVERSATION_CATEGORY>"
}
},
"pricing": {
"billable": <IS_BILLABLE?>,
"pricing_model": "CBP",
"category": "<CONVERSATION_CATEGORY>"
}
}
]
},
"field": "messages"
}
]
}
]
}Для переписок с бесплатными точками входа для origin.type и pricing.category установлено значение referral_conversion, а для pricing.billable установлено false.
Статус: сообщение прочтено
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<WHATSAPP_MESSAGE_ID>",
"status": "read",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"recipient_id": "<WHATSAPP_USER_ID>"
}
]
},
"field": "messages"
}
]
}
]
}Статус: сообщение удалено
В настоящий момент облачный API не поддерживает обновления статуса Webhooks для удаленных сообщений. Если пользователь удалит сообщение, будет получен объект Webhooks с кодом ошибки для неподдерживаемого типа сообщения:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": PHONE_NUMBER
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"errors": [{
"code": 131051,
"details": "Message type is not currently supported",
"title": "Unsupported message type"
}],
"type": "unsupported"
}]
},
"field": "messages"
}]
}]
}Обратите внимание, что нет других действий пользователя, которые могут инициировать появление этого сообщения об ошибке.
Статус: сообщение не отправлено
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<WHATSAPP_MESSAGE_ID>",
"status": "failed",
"timestamp": "<WEBHOOK_SENT_TIMESTAMP>",
"recipient_id": "<WHATSAPP_USER_ID>",
"errors": [
{
"code": <ERROR_CODE>,
"title": "<ERROR_TITLE>",
"message": "<ERROR_MESSAGE>",
"error_data": {
"details": "<ERROR_DETAILS>"
},
"href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
}
]
}
]
},
"field": "messages"
}
]
}
]
}