Уведомления о получении сообщений
Когда поступает входящее сообщение, на URL Webhooks, заданный в настройках приложения, отправляется уведомление. В этом документе рассматриваются возможные входящие сообщения и приводятся примеры.
Объекты уведомлений
Уведомления о получении сообщений могут содержать следующие объекты:
Когда вы получаете сообщение с медиафайлом, WhatsApp Business API скачивает этот файл. После этого на ваш Webhook отправляется уведомление. Оно содержит информацию, которая идентифицирует этот медиаобъект и позволяет вам найти и извлечь его. Для извлечения медиафайла используйте конечную точку Media и id медиафайла.
Примеры получения сообщений
Текстовые сообщения
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1518694235",
"text": {
"body": "Hello this is an answer"
},
"type": "text"
}]
}
Сообщение со статическим местоположением
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages":[{
"from":"16315551234",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"location":{
"address":"Main Street Beach, Santa Cruz, CA",
"latitude":38.9806263495,
"longitude":-131.9428612257,
"name":"Main Street Beach",
"url":"https://foursquare.com/v/4d7031d35b5df7744"},
"timestamp":"1521497875",
"type":"location"
}]
}
Сообщение с контактами
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"contacts": [{
"addresses": [{
"city": "Menlo Park",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "1 Hacker Way",
"type": "WORK",
"zip": "94025"
}],
"birthday": "2012-08-18",
"emails": [{
"email": "kfish@fb.com",
"type": "WORK"
}],
"ims": [{
"service": "AIM",
"user_id": "kfish"
}],
"name": {
"first_name": "Kerry",
"formatted_name": "Kerry Fisher",
"last_name": "Fisher"
},
"org": {
"company": "Meta",
"department": "WhatsApp"
},
"phones": [{
"phone": "+1 (940) 555-1234",
"type": "CELL"
},
{
"phone": "+1 (650) 555-1234",
"type": "WORK",
"wa_id": "16505551234"
}],
"urls": [{
"url": "https://www.facebook.com",
"type": "WORK"
}]
}],
"from": "16505551234",
"id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
"timestamp": "1537248012",
"type": "contacts"
}]
}
Если клиент использует iPhone, параметр contact_image будет пуст.
Сообщения с медиафайлами
Сообщение, содержащее изображение:
{
"messages": [{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"image": {
"file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
"mime_type": "image/jpeg",
"sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
"caption": "Check out my new phone!",
"status": "downloaded"
},
"timestamp": "1521497954",
"type": "image"
}]
}
Начиная с версии 2.49.1 Webhooks сообщений с медиафайлами содержит состояние и ID полученного медиафайла.
Состояние скачивания
| Состояние | Описание |
|---|---|
| Медиафайл успешно загружен |
| Медиафайл не загружен, но загрузку можно повторить с помощью конечной точки повтора |
| Не удается загрузить медиафайл |
Поле caption для сообщений с медиафайлами не является обязательным. Оно присутствует, только если пользователь указал подпись.
Сообщение, содержащее документ:
{
"messages": [{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1522189546",
"type": "document",
"document": {
"caption": "80skaraokesonglistartist",
"file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33",
"id": "fc233119-733f-49c-bcbd-b2f68f798e33",
"mime_type": "application/pdf",
"sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e",
"status": "downloaded"
}
}]
}
Голосовое сообщение:
{
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1521827831",
"type": "voice",
"voice": {
"file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
"id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
"mime_type": "audio/ogg; codecs=opus",
"sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710",
"status": "downloaded"
}
}]
}
Сообщение, содержащее стикер:
{
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1521827831",
"type": "sticker",
"sticker": {
"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
"metadata": {
"sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
"sticker-pack-name" : "Happy New Year",
"sticker-pack-publisher" : "Kerry Fisher",
"emojis": ["🐥", "😃"],
"ios-app-store-link" : "https://apps.apple.com/app/id3133333",
"android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example",
"is-first-party-sticker" : 0 | 1 # integer
},
"mime_type": "image/webp",
"sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
}
}]
}
Сообщения, создаваемые объявлениями с переходом в WhatsApp
{
"messages":[{
"from":"12345678",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"image":{
"id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
"mime_type":"image/jpeg",
"sha256":"29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db"
"caption": "Check out my product!",
},
"timestamp":"1521497954",
"type":"image",
"referral" : {
"headline": "Our new product",
"body" : "This is a great product",
"source_type": "<SOURCE_TYPE>",
"source_id": "<SOURCE_ID>",
"source_url": "<SOURCE_URL>", //for the moment, this will always be a Facebook owned domain
"video": {
"id": "e144be57-12b1-4035-a520-703fcc87ef45",
"ctwa_clid": "<CTWA_CLID>",
}
}
}]
}Ознакомьтесь с дополнительной информацией о свойстве referral.
Пример: неподдерживаемые сообщения
Обратный вызов может содержать уведомление типа unknown. Ниже приведен пример сообщения неподдерживаемого типа от клиента.
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"errors": [{
"code": 501,
"details": "Message type is not currently supported",
"title": "Unknown message type"
}],
"from": "16315551234",
"id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
"timestamp": "1531933468",
"type": "unknown"
}]
}
Пересланные сообщения
Существует возможность определить, что полученное сообщение было переслано или часто пересылается. Вот как выглядит уведомление о пересланном сообщении:
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"context": {
"forwarded": true
},
"from": "16315558011",
"id": "ABGGFmkiWVVPAgo-sOGh7pv13wVJ",
"text": {
"body": "Party at Dotty's tonight!"
},
"timestamp": "1593068329",
"type": "text"
}]
}
Вот как выглядит уведомление о часто пересылаемом сообщении:
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"context": {
"frequently_forwarded": true
},
"from": "16315558011",
"id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl",
"timestamp": "1593068225",
"type": "video",
"video": {
"id": "e144be57-12b1-4035-a520-703fcc87ef45",
"mime_type": "video/mp4",
"sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9"
}
}]
}
Включение уведомления безопасности
Если в настройках приложения для параметра show_security_notifications задано значение true, все уведомления о входящих сообщениях содержат показанные ниже идентификационные данные пользователя в объекте identity:
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages": [{
"from": "16315553601",
"id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
"identity": {
"acknowledged": true,
"created_timestamp": 1602532300000,
"hash": "Sjvjlx8G6Z0="
},
"text": {
"body": "Hi from new number 3601"
},
"timestamp": "1602532300",
"type": "text"
}]
}Сообщение, генерируемое нажатием кнопки быстрого ответа
{
"contacts": [
{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16505551234"
}
],
"messages": [
{
"button": {
"payload": "No-Button-Payload",
"text": "No"
},
"context": {
"from": "16315558007",
"id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
},
"from": "16505551234",
"id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
"timestamp": "1591210827",
"type": "button"
}
]
# If there are any errors, an errors field (array) will be present
"errors": [ { ... } ]
}
Входящие ответы на отправленные сообщения
Пользователи могут отвечать на конкретные сообщения WhatsApp. Чтобы компания могла понять контекст такого ответа, мы добавили объект context. Объект context содержит id сообщения, на которое ответил клиент, ID WhatsApp отправителя исходного сообщения и ID всех продуктов, на которые может ссылаться клиент.
Подробнее см. в разделе Ответы на сообщения.
Пример: клиент ответил на ваше сообщение
Ниже приведен пример входящего сообщения, представляющего собой ответ на сообщение, которое вы ранее отправили. Дополнительную информацию см. в разделе, посвященном объекту context ниже.
{
"contacts": [ {
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
} ],
"messages":[{
"context":{
"from":"16315558011",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf"
},
"from":"16315551234",
"id":"gBGGFlA5FpafAgkOuJbRq54qwbM",
"text":{"body":"Yes, count me in!"},
"timestamp":"1521499915",
"type":"text"
}]
}
Поле text для сообщений с медиафайлами не является обязательным. Если оно есть, значение text представляет собой подпись к отправленному медиафайлу или текст ответа (если ответ является текстовым сообщением).
Пример: клиент ответил на сообщение со списком
{
"messages": [ {
"context": {
"from": "sender_wa_id_of_context_message",
"group_id": "group_id_of_context_message",
"id": "message_id_of_context_message",
"mentions": [ "wa_id1", "wa_id2" ]
},
"from": "sender_wa_id",
"group_id": "group_id",
"id": "message_id",
"timestamp": "message_timestamp",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"title": "row-title-content-here",
"id": "unique-row-identifier-here",
"description": "row-description-content-here"
}
}
}
Пример: клиент ответил на сообщение с кнопкой ответа
{
"messages": [
{
"context": {
"from": "sender_wa_id_of_context_message",
"group_id": "group_id_of_context_message",
"id": "message_id_of_context_message",
"mentions": [ "wa_id1", "wa_id2" ]
},
"from": "sender_wa_id",
"group_id": "group_id",
"id": "message_id",
"timestamp": "message_timestamp",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "unique-button-identifier",
"title": "button-text"
}
} # end interactive node
} # end message item
] # end messages array
}Пример: клиент запрашивает информацию об определенном продукте
{
"contacts": [
{
"profile": {
"name": "customer-name"
},
"wa_id": "customer-whatsapp-ID"
}
],
"messages": [
{
"from": "customer-whatsapp-ID",
"id": "message-ID",
"text": {
"body": "Can I get this in another color?"
},
"context": {
"referred_product": {
"catalog_id": "catalog-ID",
"product_retailer_id": "product-ID"
}
},
"timestamp": "message-received-timestamp",
"type": "text"
}
]
}
Пример: клиент оформил заказ после получения сообщения об одном или нескольких продуктах
{
"messages": [ {
"from": "customer-whatsapp-id",
"group_id": "group-id",
"id": "message-ID",
"timestamp": "message-timestamp",
"type": "order"
"order": {
"catalog_id": "catalog_id",
"product_items": [
{
"product_retailer_id":"product-ID",
"quantity":"number-of-items",
"item_price":"unitary-price-of-item",
"currency":"price-currency"
},
...
],
"text":"text-message-sent-along-with-the-order"
}
}
}
Входящие системные сообщения
Системные сообщения генерируются системой при возникновении различных событий.
Пример: пользователь изменил свой номер
Если для параметра notify_user_change_number в настройках приложения установлено значение true, вы будете получать входящие системные сообщения, когда пользователь будет менять свой номер телефона.
{
"messages": [
{
"from": "16315558889",
"id": "ABGGFjFVWIifAzNzeXMtMTYzMTU1NTg4ODlAcy53aGF0c2FwcC5uZXQtMTU3NDA4MDEwMjIxMy1jaGFuZ2U",
"system": {
"body": "User A changed from +1 (631) 555-8889 to +1 (631) 555-8890",
"new_wa_id": "16315558890",
"type": "user_changed_number"
},
"timestamp": "1574080102",
"type": "system"
}
]
}
Пример: возможная смена пользователя
Если для параметра show_security_notifications в настройках приложения установлено значение true, вы будете получать входящие системные сообщения в случае, если пользователь WhatsApp (в переписке с вами) мог измениться.
Пока это уведомление не будет подтверждено через конечную точку identity, все исходящие сообщения этому пользователю будут блокироваться. Входящие сообщения будут и далее поступать в обычном порядке.
{
"messages": [
{
"from": "16315553601",
"id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ",
"system": {
"body": "Test security code change",
"identity": "Rc/eg9Rl0JA=",
"type": "user_identity_changed",
"user": "16315553601"
},
"timestamp": "1602535356",
"type": "system"
}
]
}
Типы системных сообщений
| Тип системного сообщения | Описание |
|---|---|
| Изменение номера телефона пользователя |
| Возможная смена пользователя WhatsApp |
Упоминание пользователей в сообщениях
Если вы отправите сообщение с непосредственным упоминанием определенного ID WhatsApp и кто-то на него ответит, вы увидите упомянутый ID в объекте context и в массиве mentions. Поскольку существует возможность упомянуть несколько телефонных номеров, поле mentions представляет собой массив таких номеров (даже если упомянут только один номер).
Пример: клиент отвечает на сообщение
Ниже приведен пример с ответом клиента на сообщение, которое содержит упоминания. Объект context содержит номера, упомянутые в исходном сообщении. Ответ содержит те же упомянутые номера в объекте text.
{
"messages": [{
"context": {
"from": "16315555544",
"id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
"mentions": [
"16315551000",
"16315551099"
]
},
"from": "16315551234 ",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1504902988",
"text": {
"body": "@16315551000 and @16315551099 are mentioned"
},
"type": "text"
}]
}