Envoi de messages

Ce document explique comment envoyer des messages à des utilisateur·ices WhatsApp à l’aide de l’API.

Types de messages

Vous pouvez utiliser l’API pour envoyer les types de messages suivants. Tous ces types, à l’exception des messages de réaction, peuvent être envoyés en réponse à un message précédent.

Les messages d’adresse vous permettent de demander facilement une adresse de livraison aux personnes utilisant WhatsApp.
Les messages vocaux affichent une icône audio et un lien vers un fichier audio. Lorsque la personne utilisant WhatsApp appuie sur l’icône, le client WhatsApp charge et lit le fichier audio.
Les messages de contacts vous permettent d’envoyer des informations de contact complètes directement aux personnes utilisant WhatsApp, telles que des noms, numéros de téléphone, adresses physiques et adresses e-mail.
Les messages incluant un document affichent une icône de document, liée à un document, sur laquelle une personne utilisant WhatsApp appuie pour télécharger le document.
Les messages incluant une image affichent une seule image et une légende en option.
Les messages incluant un bouton d’URL CTA interactifs vous permettent de mapper une URL sur un bouton et vous évitent d’inclure l’URL brute longue ou complexe dans le corps du message.
Les messages de flux interactifs vous permettent d’envoyer des messages structurés plus naturels ou agréables pour votre clientèle. Par exemple, vous pouvez utiliser WhatsApp Flows pour prendre des rendez-vous, parcourir les produits, recueillir les commentaires des client·es, générer de nouvelles ventes, ou autre.
Les messages de liste interactifs vous permettent de présenter aux utilisateur·ices WhatsApp une liste d’options parmi lesquelles choisir.
Les messages de demande de localisation interactifs contiennent un corps de texte et un bouton d’envoi de la localisation. Le fait d’appuyer sur ce bouton affiche un écran de partage qui permet à l’utilisateur·ice WhatsApp de partager sa localisation.
Les messages avec boutons de réponse interactifs vous permettent d’envoyer jusqu’à trois réponses prédéfinies parmi lesquelles le destinataire du message peut choisir.
Les messages de lieu vous permettent d’envoyer les coordonnées de latitude et de longitude d’un lieu à un·e utilisateur·ice WhatsApp.
Les messages incluant un sticker sont des messages WhatsApp affichant des images de stickers animés ou statiques.
Les textos sont des messages contenant uniquement un corps de texte et un aperçu de lien facultatif.
Les messages de modèle vous permettent d’envoyer des modèles de marketing, d’utilitaire et d’authentification aux utilisateur·ices WhatsApp. Contrairement à tous les autres types de messages, les messages de modèle ne nécessitent pas d’ouvrir une fenêtre de service clientèle de 24 heures entre vous et le destinataire du message pour pouvoir envoyer le message.
Les messages vidéo affichent un aperçu miniature d’une image vidéo avec une légende en option. Lorsque l’utilisateur·ice WhatsApp appuie sur l’aperçu, la vidéo se charge et se lance.
Les messages de réaction sont des réactions sous forme d’emoji que vous pouvez appliquer à un message envoyé précédemment par un·e utilisateur·ice WhatsApp.

Fenêtres de service clientèle

Quand un utilisateur ou une utilisatrice WhatsApp vous envoie un message, un minuteur de 24 heures appelé « fenêtre de service clientèle » est enclenché (ou actualisé).

À l’exception des messages basés sur un modèle, les différents types de messages ne peuvent être envoyés à un·e utilisateur·ice que si une fenêtre de service clientèle est ouverte entre vous et l’utilisateur·ice en question.

Vous pouvez envoyer des messages basés sur un modèle à tout moment, à condition que les destinataires aient consenti à recevoir des messages de votre part.

Requêtes

Toutes les requêtes d’envoi de message utilisent le point de terminaison POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages :

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

Le corps de la requête POST diffère selon le type de message que vous souhaitez envoyer, mais la charge utile reprend toujours la même syntaxe :

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

La valeur de la propriété type dans la charge utile de la requête POST indique le type de message à envoyer, et une propriété correspondant à ce type doit être incluse afin de définir le contenu du message.

Par exemple, voici une requête permettant d’envoyer un texto un·e utilisateur·ice WhatsApp. Notez que type est défini sur text et suivi d’un objet text décrivant le contenu du message :

curl 'https://graph.facebook.com/v20.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

Voici à quoi ressemblerait ce message dans le client WhatsApp une fois le texto distribué à l’utilisateur·ice WhatsApp :

Réponses

Si l’API accepte votre requête d’envoi de message et ne rencontre aucune erreur dans celle-ci, elle renvoie la réponse suivante :

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>"
      "message_status": "<PACING_STATUS>"
    }
  ]
}

Notez que cette réponse indique uniquement que l’API a accepté votre requête, elle n’indique pas que votre message a été distribué. Le statut de distribution du message est communiqué via les webhooks messages.

La propriété message_status est incluse uniquement lors de l’envoi de messages basés sur un modèle à fréquence régulée.

Webhooks

Les messages envoyés à des utilisateur·ices WhatsApp déclenchent des webhooks messages. Par conséquent, veillez à vous abonner à ce sujet pour recevoir les notifications relatives au statut des messages.

Messages Commerce

Les messages Commerce sont des messages interactifs utilisés conjointement avec un catalogue de produits. Voir Partager des produits avec votre clientèle pour découvrir comment utiliser ces types de messages.

Réponses

Vous pouvez envoyer tout type de message en réponse à un message précédent. Le message précédent apparaîtra en haut du nouveau message, cité dans une bulle contextuelle.

Limites

La bulle contextuelle n’apparaîtra pas en haut du message réponse distribué dans les cas suivants :

• Le message précédent a été supprimé ou transféré vers le stockage à long terme (les messages sont généralement transférés vers le stockage à long terme au bout de 30 jours, sauf si vous avez activé le stockage local).
• Vous répondez par un message avec fichier audio, un message avec image ou un message vidéo et l’utilisateur·ice WhatsApp exécute KaiOS.
• Vous utilisez le client WhatsApp pour répondre avec un message Appuyer pour parler et l’utilisateur·ice WhatsApp exécute KaiOS.
• Vous répondez avec un message basé sur un modèle.

Syntaxe de la requête

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

Corps de la requête POST

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "context": {
    "message_id": "WAMID_TO_REPLY_TO"
  },

  /* Message type and type contents goes here */

}

Paramètres du corps de la publication

Exemple de requête

Exemple de texto envoyé en réponse à un message précédent.

curl 'https://graph.facebook.com/v19.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "context": {
    "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA="
  },
  "type": "text",
  "text": {
    "body": "You'\''re welcome, Pablo!"
  }
}'

Contenus multimédias

Les contenus multimédias envoyés dans un message doivent être importés sur le numéro de téléphone professionnel qui enverra le message, ou vous devez héberger l’élément de contenu sur un serveur public et inclure son URL dans la requête d’envoi de message.

Afin de réduire la probabilité d’erreurs et d’éviter les requêtes inutiles à votre serveur public, nous recommandons d’importer votre contenu multimédia et d’utiliser ses ID lors de l’envoi de messages.

Mise en cache de contenus multimédias HTTP

L’API Cloud WhatsApp prend en charge la mise en cache HTTP de contenus multimédias. Si vous utilisez un lien (link) vers un élément de contenu multimédia sur votre serveur (plutôt que l’id d’un élément que vous avez importé sur nos serveurs), vous pouvez nous demander de mettre votre élément en cache pour le réutiliser dans de futurs messages, en incluant les en-têtes ci-dessous dans la réponse de votre serveur lorsque nous demandons l’élément. Si aucun de ces en-têtes n’est inclus, nous ne mettrons pas votre élément en cache.

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

L’en-tête Cache-Control nous indique comment gérer la mise en cache des éléments. Nous prenons en charge les directives suivantes :

• max-age=n : indique pendant combien de secondes (n) l’élément doit être mis en cache. Nous réutiliserons l’élément mis en cache dans les messages suivants jusqu’à ce que ce délai soit dépassé, après quoi nous demanderons à nouveau l’élément, si nécessaire. Exemple : Cache-Control: max-age=604800.
• no-cache : indique que l’élément peut être mis en cache, mais devrait être mis à jour si la valeur de l’en-tête Last-Modified est différente de celle de la réponse précédente. Nécessite l’en-tête Last-Modified. Exemple : Cache-Control: no-cache.
• no-store : indique que l’élément ne devrait pas être mis en cache. Exemple : Cache-Control: no-store.
• private : indique que l’élément est personnalisé pour le ou la destinataire et ne devrait pas être mis en cache.

Last-Modified

Indique la date de dernière modification de l’élément. Cet en-tête est utilisé avec Cache-Control: no-cache. Si la valeur de Last-Modified est différente de celle de la réponse précédente, et si Cache-Control: no-cache est inclus dans la réponse, nous mettrons à jour notre version en cache de l’élément en ajoutant l’élément dans la réponse. Exemple : Date: Tue, 22 Feb 2022 22:22:22 GMT.

ETag

L’en-tête ETag est une chaîne unique qui identifie une version spécifique d’un élément. Exemple : ETag: "33a64df5". Cet en-tête est ignoré à moins que les en-têtes Cache-Control et Last-Modified ne figurent pas dans la réponse. Dans ce cas, nous mettons l’élément en cache selon notre propre logique interne (que nous ne divulguons pas).

Exemple de réponse avec des en-têtes

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

Ordre de diffusion lorsqu’il y a plusieurs messages

Lorsque vous envoyez une série de messages, leur ordre de diffusion ne correspond pas forcément à celui de vos requêtes d’API. Pour garantir l’ordre de diffusion de vos messages, confirmez la réception d’un statut delivered dans un webhook de messages avant d’envoyer le message suivant de votre liste.

TTL (Time-To-Live, Durée de vie)

Quand nous ne parvenons pas à distribuer un message à un utilisateur ou une utilisatrice WhatsApp, nous poursuivons les tentatives de distribution du message durant une période appelée TTL (Time-To-Live). Si nous ne parvenons pas à distribuer un message pendant sa TTL, nous ne tentons plus de le renvoyer ensuite.

• La TTL de tous les messages, à l’exception de ceux qui sont basés sur un modèle d’authentification, est de 30 jours.
• Les messages basés sur un modèle d’authentification ont une TTL par défaut de 10 minutes.

Vous pouvez personnaliser ces valeurs par défaut en définissant une TTL personnalisée sur les modèles d’authentification et utilitaires. Voir Personnaliser le TTL (Time-To-Live).

Si vous envoyez un message et que vous ne recevez pas le webhook messages correspondant indiquant que le message a été distribué avant la fin de la TTL, vous pouvez considérer le message comme abandonné.

Notez que si un message échoue pour une autre raison et que cela déclenche un webhook messages d’échec de distribution, il se peut que vous receviez le webhook avec un léger retard. Par conséquent, nous vous recommandons de définir une petite marge avant de considérer un message comme abandonné.

Résolution des problèmes

Si vous rencontrez des problèmes avec la distribution des messages, consultez Message non distribué.