# Ricevere immagini WhatsApp

Una foto o un'immagine inviata da un contatto arriva come messaggio in entrata con `image`: un riferimento al file che Bird ha archiviato per te, più l'eventuale didascalia digitata sotto.

## Cosa contiene un'immagine in entrata

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

| Campo       | Cosa contiene                                                                       |
| ----------- | ----------------------------------------------------------------------------------- |
| `id`        | Il file archiviato, da passare come `media_id` quando scarichi i byte               |
| `url`       | Un URL Bird, da scaricare con la tua chiave API                                     |
| `mime_type` | Il tipo di media che WhatsApp ha riportato per il file, ad esempio `image/jpeg`     |
| `caption`   | Il testo che il contatto ha digitato sotto l'immagine; assente se non ne ha inviato |

`id` e `mime_type` compaiono solo su un'immagine in entrata: Bird li ricava entrambi scaricando il file, e non ha mai archiviato quello che hai inviato tu. Un'immagine in uscita viene riletta con il `url` che hai fornito e senza `id`.

Tratta `mime_type` come un'indicazione di WhatsApp piuttosto che come una garanzia, e basa la logica su di esso anziché sull'estensione del file in `url`, che non ne contiene.

## Scaricare i byte

`url` e `id` puntano entrambi allo stesso file archiviato: passa l'ID del messaggio e il `id` del media al metodo media del canale, in qualsiasi SDK, nella CLI o in cURL. La sezione [scaricare media in entrata](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) dell'hub riporta quella chiamata in ogni linguaggio, insieme alle regole di redirect e header che segue.

Il messaggio e il suo media scadono insieme, 30 giorni dopo l'arrivo del messaggio; la sezione [scaricare media in entrata](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) dell'hub gestisce quella finestra e ciò che le letture restituiscono una volta trascorsa. Archivia qualsiasi immagine che ti serve più a lungo finché il messaggio è ancora leggibile.

## Il payload del webhook

`whatsapp.received` porta il ramo `image` sull'envelope dell'evento, riferimento media incluso:

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

Il webhook si attiva all'arrivo del messaggio, che è anche il momento in cui inizia la finestra di conservazione: un endpoint che accoda il download anziché eseguirlo inline ha l'intera finestra per recuperare.

## Aspetti da tenere d'occhio

- **La didascalia appartiene al contatto.** Arriva come testo semplice senza formattazione né informazioni sulle entità, quindi renderizzala come testo.
- **Un'immagine per messaggio.** Un contatto che invia più foto produce più messaggi in entrata, ciascuno con il proprio `id` e il proprio riferimento media. Raggruppali per `from` e orario di arrivo; nessun array li raccoglie.

## Passi successivi

- [Come funziona la ricezione](/docs/guides/whatsapp/receiving-whatsapp): l'envelope in entrata, il download dei media e il webhook `whatsapp.received`
- [Messaggi immagine WhatsApp](/docs/guides/whatsapp/message-types/images): il lato invio dello stesso ramo
- [Ricevere documenti](/docs/guides/whatsapp/receiving-whatsapp/documents): la stessa struttura media, con il nome file del mittente
- [Eventi WhatsApp](/docs/guides/whatsapp/events): l'elenco completo degli eventi, tramite API o webhook

## 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)