Recevoir des images WhatsApp

Une photo ou un graphique envoyé par un contact arrive sous forme de message entrant contenant image : une référence au fichier que Bird a stocké pour vous, plus la légende éventuellement saisie en dessous.

Ce que contient une image entrante

Exemple de code

{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "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?"
  },
  "created_at": "2026-08-25T09:04:11Z"
}

Champ	Ce qu'il contient
id	Le fichier stocké, à transmettre comme media_id lors de la récupération des octets
url	Une URL Bird, à récupérer avec votre clé API
mime_type	Le type de média que WhatsApp a signalé pour le fichier, par exemple image/jpeg
caption	Le texte que le contact a saisi sous l'image ; absent s'il n'en a envoyé aucun

id et mime_type n'apparaissent que sur une image entrante : Bird les obtient tous les deux en récupérant le fichier, et n'a jamais stocké celui que vous avez envoyé. Une image sortante est relue avec le url que vous avez fourni et sans id.

Traitez mime_type comme le rapport de WhatsApp plutôt que comme une garantie, et branchez dessus au lieu de vous baser sur l'extension de fichier dans url, qui n'en contient aucune.

Récupérer les octets

url et id pointent tous les deux vers le même fichier stocké : transmettez l'identifiant du message et le id média à la méthode média du canal, dans n'importe quel SDK, le CLI, ou cURL. La page récupérer les médias entrants du hub contient cet appel dans chaque langage, ainsi que les règles de redirection et d'en-tête qu'il suit.

Le message et ses médias expirent ensemble, 30 jours après l'arrivée du message ; la page récupérer les médias entrants du hub décrit cette fenêtre et ce que les lectures renvoient une fois qu'elle est dépassée. Stockez toute image dont vous avez besoin plus longtemps tant que le message est encore lisible.

Le contenu du webhook

whatsapp.received porte la branche image sur l'enveloppe d'événement, référence média incluse :

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" },
    "to": { "phone_number": "+13124495569" },
    "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?"
    },
    "tags": null,
    "metadata": null
  }
}

Le webhook se déclenche à l'arrivée du message, ce qui correspond aussi au début de la fenêtre de rétention ; un endpoint qui met la récupération en file d'attente au lieu de la traiter en ligne dispose donc de toute la fenêtre pour rattraper.

Points à surveiller

La légende appartient au contact. Elle arrive en texte brut, sans formatage ni information d'entité ; affichez-la donc comme du texte.
Une image par message. Un contact qui envoie plusieurs photos produit plusieurs messages entrants, chacun avec son propre id et sa propre référence média. Regroupez-les par from et heure d'arrivée ; aucun tableau ne les rassemble.

Étapes suivantes

Fonctionnement de la réception : l'enveloppe entrante, la récupération des médias et le webhook whatsapp.received
Messages image WhatsApp : le côté envoi de la même branche
Recevoir des documents : la même structure média, avec le nom de fichier de l'expéditeur
Événements WhatsApp : la liste complète des événements, via le API ou les webhooks

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