Notifications de messages reçus
Lorsque vous recevez un message, une notification est envoyée à l’URL webhook que vous avez définie dans les paramètres de l’application. Ce document passe en revue les messages que vous pouvez recevoir, avec des exemples.
Objets des notifications
Les notifications de messages reçus peuvent contenir les objets suivants :
Quand vous recevez un message multimédia, le client de l’API WhatsApp Business télécharge le contenu multimédia. Une notification est envoyée à votre webhook quand le téléchargement est terminé. Cette notification contient des informations qui identifient l’objet multimédia. Celles-ci vous permettent également de trouver et de récupérer l’objet. Utilisez le point de terminaison des contenus multimédias et l’id du contenu multimédia pour récupérer ce dernier.
Exemples de messages reçus
Texto
{
"contacts": [{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315551234"
}],
"messages":[{
"from": "16315551234",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1518694235",
"text": {
"body": "Hello this is an answer"
},
"type": "text"
}]
}
Message de localisation statique
{
"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"
}]
}
Message de contact
{
"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"
}]
}
Le paramètre contact_image est vide si le client ou la cliente utilise un iPhone.
Messages multimédias
Message contenant une 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"
}]
}
Les webhooks de message multimédia version 2.49.1 contiennent l’état et l’ID du contenu multimédia reçu.
États de téléchargement
| État | Description |
|---|---|
| Le contenu multimédia a bien été téléchargé. |
| Le contenu multimédia n'a pas été téléchargé, mais le téléchargement peut être relancé à partir du point de terminaison retry. |
| Le contenu multimédia ne peut pas être téléchargé. |
Le champ caption est facultatif pour les messages multimédias. Il est inclus dans le message uniquement si l’utilisateur·ice a configuré une légende.
Message contenant un document :
{
"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"
}
}]
}
Message vocal :
{
"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"
}
}]
}
Message contenant un sticker :
{
"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"
}
}]
}
Message généré à partir de publicités clic vers 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>",
}
}
}]
}En savoir plus sur la propriété referral
Exemple : messages non pris en charge
Vous pouvez recevoir une notification de rappel unknown. Dans cet exemple, le client ou la cliente a envoyé un type de message qui n’est pas pris en charge.
{
"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"
}]
}
Messages transférés
Vous pouvez voir si un message que vous avez reçu a été transféré ou est fréquemment transféré. Voici un exemple de notification pour un message transféré :
{
"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"
}]
}
Voici un exemple de notification pour un message fréquemment transféré :
{
"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"
}
}]
}
Notifications de sécurité activées
Si le paramètre show_security_notifications est défini sur true dans les paramètres de l’application, toutes les notifications de message entrant comprendront les informations suivantes sur l’identité de l’utilisateur·ice, contenus dans l’objet 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"
}]
}Message à partir d’un clic sur un bouton de réponse rapide
{
"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": [ { ... } ]
}
Réponses entrantes aux messages envoyés
Les utilisateur·ices peuvent répondre à un message spécifique dans WhatsApp. Afin que les entreprises disposent de plus de contexte sur la réponse à un message, nous intégrons l’objet context. Cet objet context contient l’id du message auquel le ou la client·e a répondu, ainsi que l’ID WhatsApp de l’expéditeur·ice du message d’origine et les ID des produits auxquels le ou la client·e fait référence, le cas échéant.
Pour en savoir plus, consultez la page Comment répondre à un message.
Exemple : réponse d’un·e client·e à votre message
Dans cet exemple, le client ou la cliente répond à un message que vous lui avez envoyé. Pour en savoir plus, consultez la section sur l’objet context ci-dessous.
{
"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"
}]
}
Le champ text est facultatif pour les messages multimédias. S’il est présent, la valeur du champ text correspond à la légende du contenu multimédia envoyé ou au corps de la réponse, si la réponse est un message texte.
Exemple : réponse d’un client ou d’une cliente à un message liste
{
"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"
}
}
}
Exemple : réponse d’un client ou d’une cliente à un message contenant un bouton de réponse
{
"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
}Exemple : demande d’information sur un produit spécifique
{
"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"
}
]
}
Exemple : commande passée après la réception d’un message contenant un seul ou plusieurs produits
{
"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"
}
}
}
Messages système entrants
Les messages système sont générés par le système après certains évènements.
Exemple : l’utilisateur·ice a modifié son numéro
Si le paramètre notify_user_change_number est défini sur true dans les paramètres de l’application, vous recevrez un message système quand un utilisateur ou une utilisatrice changera de numéro de téléphone.
{
"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"
}
]
}
Exemple : potentiel changement d’utilisateur·ice
Si le paramètre show_security_notifications est défini sur true dans les paramètres de l’application, vous recevrez un message système quand un utilisateur ou un utilisatrice (dans une conversation avec vous) a potentiellement changé dans WhatsApp.
Tant que cette notification n’est pas traitée avec le point de terminaison identity, tous les messages sortants adressés à cet utilisateur ou cette utilisatrice seront bloqués. Les messages entrants resteront autorisés.
{
"messages": [
{
"from": "16315553601",
"id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ",
"system": {
"body": "Test security code change",
"identity": "Rc/eg9Rl0JA=",
"type": "user_identity_changed",
"user": "16315553601"
},
"timestamp": "1602535356",
"type": "system"
}
]
}
Types de message système
| Type de message système | Description |
|---|---|
| Le numéro de téléphone de l’utilisateur·ice a changé. |
| L’utilisateur·ice a potentiellement changé dans WhatsApp. |
Mention des utilisateur·ices dans les messages
Quand vous envoyez un message qui mentionne directement un ID WhatsApp spécifique et qu’un utilisateur ou une utilisatrice répond à ce message, vous verrez l’ID mentionné dans l’objet context et dans l’ensemble de mentions. Étant donné que plusieurs numéros de téléphone peuvent être mentionnés, le champ mentions contient un ensemble de numéros de téléphone, même si un seul numéro de téléphone est mentionné.
Exemple : réponse d’un client ou d’une cliente à votre message
Dans cet exemple, le client ou la cliente répond à un message contenant des mentions. L’objet context contient les numéros mentionnés dans le message d’origine. La réponse dans l’objet text mentionne à nouveau les mêmes numéros.
{
"messages": [{
"context": {
"from": "16315555544",
"id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
"mentions": [
"16315551000",
"16315551099"
]
},
"from": "16315551234 ",
"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1504902988",
"text": {
"body": "@16315551000 and @16315551099 are mentioned"
},
"type": "text"
}]
}