Recevoir des documents WhatsApp

Un PDF, un tableur ou tout autre fichier qu'un contact joint arrive sous forme de message entrant portant document : la référence média partagée, plus le nom que son propre appareil a donné au fichier.

Ce que contient un document entrant

Exemple de code

{
  "id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "document": {
    "id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
    "mime_type": "application/pdf",
    "filename": "invoice-A1B2C3.pdf"
  },
  "created_at": "2026-08-25T09:15:02Z"
}

Champ	Ce qu'il contient
id	Le fichier stocké, à passer 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 signalé par WhatsApp pour le fichier, par exemple application/pdf
filename	Le nom donné au fichier par l'expéditeur ; absent si le message n'en contenait pas
caption	Le texte que le contact a saisi sous le document ; absent s'il n'en a pas envoyé

filename est le seul champ que le côté envoi et le côté réception utilisent différemment : à l'envoi, c'est le nom que vous voulez afficher dans la conversation, et dans un message entrant, c'est ce que l'appareil du contact a fourni.

Récupérer les octets

Passez l'identifiant du message et le id du média à la méthode média du canal. La page récupérer les médias entrants du hub détaille cet appel dans chaque langage, ainsi que les règles de redirection et d'en-tête qu'il suit, et définit la fenêtre de rétention dans laquelle le fichier reste disponible.

N'écrivez pas filename sur le disque tel quel. C'est du texte contrôlé par un attaquant provenant d'un expéditeur non authentifié : il peut contenir des séparateurs de chemin, des séquences de traversée, une seconde extension trompeuse ou un nom qui entre en collision avec un fichier que vous détenez déjà. Générez votre propre clé de stockage à partir du id du média, conservez filename comme libellé d'affichage, et décidez quoi faire du fichier à partir de mime_type plutôt que de l'extension revendiquée par le nom.

Le payload du webhook

whatsapp.received porte la branche document sur l'enveloppe d'événement :

Exemple de code

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:15:02.336Z",
  "data": {
    "whatsapp_id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "document": {
      "id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
      "mime_type": "application/pdf",
      "filename": "invoice-A1B2C3.pdf"
    },
    "tags": null,
    "metadata": null
  }
}

Un flux de réclamations ou d'intégration qui collecte des documents peut router sur mime_type ici et mettre la récupération en file d'attente, puisque les octets restent disponibles pendant toute la fenêtre de rétention.

Points de vigilance

mime_type est le rapport de WhatsApp sur le fichier et ne dit rien de ce qu'il contient réellement. Analysez tout ce que vous acceptez d'un contact et validez la structure propre du fichier avant de le parser.
Une légende et un nom de fichier sont des champs distincts. Un contact qui saisit une note en joignant le fichier remplit caption ; filename provient toujours de son appareil.

Étapes suivantes

Fonctionnement de la réception : l'enveloppe entrante, la récupération des médias et le webhook whatsapp.received
Messages de document WhatsApp : le côté envoi de la même branche
Recevoir des images : la même structure média pour la photo d'un document
É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