Documentation
Sign inGet started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

Recevoir des messages WhatsApp

Les messages entrants arrivent sur la même ressource que les messages sortants, sans endpoint de boîte de réception distinct à interroger. Consultez-les avec la liste des messages dans le tableau de bord, ou via le API avec GET /v1/whatsapp/messages/{id} après avoir filtré la liste sur les messages entrants.
Chaque message entrant prolonge la fenêtre de service client à 24 heures après l'horodatage de ce message, ce qui rend possible une réponse libre de votre part. Un message qui arrive tardivement sur Bird porte donc la fenêtre que son contact a effectivement accordée, et une échéance ultérieure déjà enregistrée n'est jamais raccourcie.

Contenu d'un message entrant

Chaque message entrant partage une même enveloppe : un id, direction: "inbound", le contact dans from, votre propre numéro dans to, un status de received, et un created_at. Un seul champ de contenu l'accompagne, indiquant ce que le contact a envoyé :
Exemple de code
{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "text": { "body": "Is my order out for delivery yet?" },
  "created_at": "2026-08-25T09:04:11Z"
}
from identifie le contact par l'identité que WhatsApp signale : un phone_number E.164, un bsuid, ou les deux, plus les username et display_name qu'il publie. Un contact qui a adopté un nom d'utilisateur WhatsApp peut vous joindre sans numéro de téléphone ; consultez les identifiants utilisateur limités à l'entreprise pour savoir quoi stocker et comment demander un numéro.
Un de ces champs de contenu, un arm, porte ce que le contact a envoyé, et exactement un seul arm est défini par message. Chacun a sa propre page, avec la forme de lecture, le payload whatsapp.received, et les points d'attention :
ChampContenu d'un message entrant
textbody, le message que le contact a tapé
imageUn id, url, mime_type, et éventuellement caption
videoLes mêmes champs média, plus éventuellement caption
audioLes mêmes champs média, plus voice pour une note vocale ; pas de légende
stickerLes mêmes champs média, plus animated
documentLes mêmes champs média, plus éventuellement filename et caption
locationlatitude et longitude, et parfois name, address, ou un url
contact_cardsUne ou plusieurs fiches contact partagées par le contact
interactive_replyLe slug et le text du bouton ou de la ligne que le contact a tapé
unsupportedLe type de contenu WhatsApp que le API ne modélise pas, comme une commande
Deux appuis arrivent sur un arm auquel vous ne vous attendez peut-être pas. Une demande de localisation répond comme un location entrant ordinaire, et une demande de coordonnées répond comme contact_cards, donc une intégration qui surveille uniquement interactive_reply pour un appui les manque toutes les deux.

Récupérer les médias entrants

Un image, video, audio, sticker ou document entrant arrive sous forme de référence à un fichier stocké par Bird, et non comme le fichier lui-même :
Exemple de code
{
  "image": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "image/jpeg",
    "caption": "Is this the right part?"
  }
}
Récupérez les octets avec la méthode média du canal, en passant l'id du message et le id du média :
const media = await bird.whatsapp.messages.media(
  "wam_01kya19eknftrs2s6p82asmvnh",
  "waf_01kyb2m4xq7whs0d8n3prv6tez",
);
console.log(media.contentType, media.contentLength);
Vous récupérez les octets avec le mime_type de stockage déclaré pour eux. Un id que Bird ne reconnaît pas renvoie 404, et un message sortant n'a pas de média stocké à servir.
Un message reste lisible pendant 30 jours après son arrivée, et ses médias ne lui survivent jamais. Cet endpoint lit le message avant de servir le fichier, donc une fois cette fenêtre passée, les deux répondent 404. Stockez tout fichier dont vous avez besoin plus longtemps tant que le message est encore lisible. Le seul cas qui se termine plus tôt est celui où les octets stockés disparaissent avant la fin de la fenêtre : la récupération répond 410 E15021, et le message reste lisible avec le mime_type et le caption du média.
En coulisses, cet endpoint répond 302 avec une URL présignée valable 15 minutes. Les SDK et le CLI gèrent cette redirection pour vous. En appelant directement, l'URL présignée porte ses propres identifiants, donc la requête redirigée ne doit pas envoyer en plus votre en-tête Authorization. Envoyer les deux échoue. curl -L supprime l'en-tête lors d'une redirection cross-host automatiquement ; un client qui transmet les en-têtes tels quels doit récupérer le Location comme une requête séparée, non authentifiée.

Réponses avec citation

in_reply_to_message_id identifie le message auquel un message entrant répond, quand WhatsApp le marque comme réponse :
Exemple de code
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that one" }
}
WhatsApp ne marque pas chaque réponse, et une réponse non marquée ne porte aucun ID. Le champ est aussi omis quand le message cité ne peut pas être rattaché à un message que Bird détient : un message envoyé avant que cet espace de travail ait commencé à les enregistrer, ou un message au-delà des 15 jours pendant lesquels Bird conserve les identifiants de messages de WhatsApp. Une absence omet le champ plutôt que d'en signaler un, ce qui se lit de la même façon qu'une réponse qui ne répond à rien.
Traitez le champ comme un indice plutôt qu'une clé. metadata sur votre propre envoi n'aide pas ici, car il reste sur votre message et ne voyage jamais jusqu'à la réponse du contact, donc une intégration qui doit savoir à quelle question une réponse correspond suit elle-même la dernière question posée à ce contact. Consultez Citer un message pour le côté sortant.

Le webhook

Abonnez-vous à whatsapp.received pour agir sur un message entrant dès son arrivée plutôt que d'interroger la liste. Le payload porte le contenu en plus de l'enveloppe d'événement, donc un endpoint n'a pas besoin de lecture complémentaire :
Exemple de code
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
    "to": { "phone_number": "+13124495569" },
    "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "interactive_reply": {
      "type": "button",
      "button": { "slug": "cancel-booking", "text": "Cancel" }
    },
    "tags": null,
    "metadata": null
  }
}
Consultez les événements WhatsApp pour l'enveloppe complète et le reste de la liste d'événements.

Étapes suivantes

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 channelComprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builderExplorer la fonctionnalitéWhatsApp
Essayez la pratique et obtenez un guide d'implémentation