Recevoir des messages texte WhatsApp

Un contact qui écrit dans le chat produit un message entrant portant text. C'est le bras entrant le plus courant, et celui qui ouvre ou réinitialise la fenêtre de service client.

Ce que contient un texte entrant

text.body contient ce que le contact a saisi, et rien d'autre ne figure sur le bras :

Exemple de code

{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "text": { "body": "Is my order out for delivery yet?" },
  "created_at": "2026-08-25T09:04:11Z"
}

preview_url est un champ côté envoi. Un texte entrant ne porte aucun indicateur d'aperçu de lien, quel que soit le rendu du propre client du contact, donc une URL dans body est lue comme faisant partie du texte.

Le schéma de lecture ne déclare aucun maximum pour un body entrant. La limite de 4 096 caractères appartient au côté envoi, donc dimensionnez votre stockage comme du texte sans limite plutôt que selon un plafond que le bras entrant ne garantit pas.

Un texte envoyé en réponse citée

Lorsque le contact répond à l'un de vos messages en le citant, le bras reste inchangé et in_reply_to_message_id désigne le message auquel il a répondu :

Exemple de code

{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that one" },
  "created_at": "2026-08-25T09:06:02Z"
}

WhatsApp ne marque pas chaque réponse, et une réponse non marquée ne porte aucun ID. Consultez les réponses citées sur le hub pour savoir ce que la résolution peut manquer et comment corréler sans elle.

Le payload du webhook

whatsapp.received porte le même bras sur l'enveloppe d'événement, donc un endpoint peut agir sur le texte sans relire le message :

Exemple de code

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
    "to": { "phone_number": "+13124495569" },
    "text": { "body": "Is my order out for delivery yet?" },
    "tags": null,
    "metadata": null
  }
}

Points à surveiller

Un texte est le moyen le moins coûteux pour un contact de rouvrir la fenêtre. Tout message entrant réinitialise la fenêtre de service à 24 heures, et un texte est ce que la plupart des contacts envoient ; une réponse libre de votre part est livrable dès cet instant.
from peut arriver sans numéro de téléphone. Un contact qui a adopté un nom d'utilisateur WhatsApp vous contacte par identifiant utilisateur à portée commerciale, donc lisez l'identité depuis from plutôt que de supposer que from.phone_number est défini.
Le corps est la saisie propre du contact. Un appui sur un élément que vous avez envoyé arrive plutôt comme une réponse interactive sur son propre bras.

Étapes suivantes

Fonctionnement de la réception : l'enveloppe entrante, la récupération des médias et le webhook whatsapp.received
Messages texte brut WhatsApp : le côté envoi du même bras
Recevoir des réponses interactives : ce qu'un appui sur un bouton ou une ligne de liste produit
Envoyer des messages WhatsApp : répondre dans la fenêtre de service et citer un message

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channel Comprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builder Explorer la fonctionnalitéWhatsApp

Essayez la pratique et obtenez un guide d'implémentation