# 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](/docs/guides/whatsapp/message-log) 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](/docs/knowledge-base/whatsapp/customer-service-window) à 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é :

```json
{
  "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](/docs/guides/whatsapp/business-scoped-user-ids) 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 :

| Champ                                                                               | Contenu d'un message entrant                                               |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`text`](/docs/guides/whatsapp/receiving-whatsapp/plain-text)                       | `body`, le message que le contact a tapé                                   |
| [`image`](/docs/guides/whatsapp/receiving-whatsapp/images)                          | Un `id`, `url`, `mime_type`, et éventuellement `caption`                   |
| [`video`](/docs/guides/whatsapp/receiving-whatsapp/video)                           | Les mêmes champs média, plus éventuellement `caption`                      |
| [`audio`](/docs/guides/whatsapp/receiving-whatsapp/audio)                           | Les mêmes champs média, plus `voice` pour une note vocale ; pas de légende |
| [`sticker`](/docs/guides/whatsapp/receiving-whatsapp/stickers)                      | Les mêmes champs média, plus `animated`                                    |
| [`document`](/docs/guides/whatsapp/receiving-whatsapp/documents)                    | Les mêmes champs média, plus éventuellement `filename` et `caption`        |
| [`location`](/docs/guides/whatsapp/receiving-whatsapp/location)                     | `latitude` et `longitude`, et parfois `name`, `address`, ou un `url`       |
| [`contact_cards`](/docs/guides/whatsapp/receiving-whatsapp/contact-cards)           | Une ou plusieurs fiches contact partagées par le contact                   |
| [`interactive_reply`](/docs/guides/whatsapp/receiving-whatsapp/interactive-replies) | Le `slug` et le `text` du bouton ou de la ligne que le contact a tapé      |
| [`unsupported`](/docs/guides/whatsapp/receiving-whatsapp/unsupported)               | Le 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](/docs/guides/whatsapp/message-types/interactive/location-requests) répond comme un `location` entrant ordinaire, et une [demande de coordonnées](/docs/guides/whatsapp/message-types/interactive/contact-info-requests) 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 :

```json
{
  "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 :

**TypeScript**

```typescript
const media = await bird.whatsapp.messages.media(
  "wam_01kya19eknftrs2s6p82asmvnh",
  "waf_01kyb2m4xq7whs0d8n3prv6tez",
);
console.log(media.contentType, media.contentLength);
```

Examples: [TypeScript](/fr-fr/documentation/guides/whatsapp/receiving-whatsapp.ts.md) · [Python](/fr-fr/documentation/guides/whatsapp/receiving-whatsapp.py.md) · [Go](/fr-fr/documentation/guides/whatsapp/receiving-whatsapp.go.md) · [PHP](/fr-fr/documentation/guides/whatsapp/receiving-whatsapp.php.md) · [CLI](/fr-fr/documentation/guides/whatsapp/receiving-whatsapp.cli.md) · [MCP](/fr-fr/documentation/guides/whatsapp/receiving-whatsapp.mcp.md) · [cURL](/fr-fr/documentation/guides/whatsapp/receiving-whatsapp.curl.md)

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`](/docs/api/errors/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 :

```json
{
  "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](/docs/guides/whatsapp/sending-whatsapp#quoting-a-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 :

```json
{
  "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](/docs/guides/whatsapp/events#webhooks) pour l'enveloppe complète et le reste de la liste d'événements.

## Étapes suivantes

- [Messages de service](/docs/guides/whatsapp/message-types) : le côté envoi des mêmes arms de contenu
- [Envoyer des messages WhatsApp](/docs/guides/whatsapp/sending-whatsapp) : répondre dans la fenêtre de service, et citer un message
- [Événements WhatsApp](/docs/guides/whatsapp/events) : la liste complète des événements, via le API ou les webhooks
- [Journal WhatsApp](/docs/guides/whatsapp/message-log) : parcourir la conversation dans le tableau de bord

## 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](/whatsapp) (product)

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