# 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

```json
{
  "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](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) 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 :

```json
{
  "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](/docs/guides/whatsapp/receiving-whatsapp) : l'enveloppe entrante, la récupération des médias et le webhook `whatsapp.received`
- [Messages de document WhatsApp](/docs/guides/whatsapp/message-types/documents) : le côté envoi de la même branche
- [Recevoir des images](/docs/guides/whatsapp/receiving-whatsapp/images) : la même structure média pour la photo d'un document
- [Événements WhatsApp](/docs/guides/whatsapp/events) : la liste complète des événements, via le API ou les webhooks

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)