# Ricevere audio WhatsApp

L'audio inviato da un contatto arriva come messaggio in entrata con `audio`. Il ramo copre sia una nota vocale registrata nella chat sia un file audio allegato, e `voice` è ciò che distingue i due.

## Cosa contiene un audio in entrata

```json
{
  "id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "audio": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "audio/ogg; codecs=opus",
    "voice": true
  },
  "created_at": "2026-08-25T09:07:32Z"
}
```

| Campo       | Cosa contiene                                                                                |
| ----------- | -------------------------------------------------------------------------------------------- |
| `id`        | Il file archiviato, da passare come `media_id` quando si scaricano i byte                    |
| `url`       | Un URL Bird, da richiamare con la chiave API                                                 |
| `mime_type` | Il media type riportato da WhatsApp, ad esempio `audio/ogg; codecs=opus` per una nota vocale |
| `voice`     | `true` per una nota vocale registrata nella chat, anziché un file audio allegato             |

`caption` non esiste su questo ramo in nessuna delle due direzioni, quindi un messaggio audio non porta mai del testo con sé. Un contatto che vuole aggiungere parole invia un [messaggio di testo](/docs/guides/whatsapp/receiving-whatsapp/plain-text) separato.

Una nota vocale viene scaricata automaticamente nel client WhatsApp e può essere trascritta lì per il destinatario. Bird passa l'audio così com'è e non lo trascrive, quindi la trascrizione che il contatto vede nella propria app non fa parte del messaggio che leggi tu.

## Scaricare i byte

Passa l'ID del messaggio e il `id` del media al metodo media del canale. La guida [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.

`mime_type` indica il container e il codec: una nota vocale è Opus in un container Ogg, non l'MP3 o l'AAC che un allegato probabilmente usa. Leggi il tipo dal campo e non dall'estensione del file in `url`, che non ne ha, e verificalo prima di passare i byte a un servizio di trascrizione che accetta solo alcuni formati. Il messaggio e il suo media scadono insieme, 30 giorni dopo l'arrivo del messaggio; la guida [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.

## Il payload del webhook

`whatsapp.received` porta il ramo `audio` sull'envelope dell'evento, flag `voice` incluso:

```json
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:07:32.451Z",
  "data": {
    "whatsapp_id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "audio": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "audio/ogg; codecs=opus",
      "voice": true
    },
    "tags": null,
    "metadata": null
  }
}
```

Un flusso automatizzato che risponde alle note vocali legge `voice` qui, prima di scaricare qualsiasi cosa: una coda di supporto che trascrive le registrazioni ma inoltra i file musicali allegati può diramare sul solo flag.

## Aspetti da considerare

- **Leggi `voice` come un flag che indica una nota vocale.** Qualsiasi altro valore, incluso un campo assente, è un normale allegato audio.
- **La durata non viene riportata.** Il ramo non include la lunghezza, quindi leggila dal file dopo il download se una coda ne ha bisogno.

## Passaggi successivi

- [Come funziona la ricezione](/docs/guides/whatsapp/receiving-whatsapp): l'envelope in entrata, il download dei media e il webhook `whatsapp.received`
- [Messaggi audio WhatsApp](/docs/guides/whatsapp/message-types/audio): il lato invio dello stesso ramo
- [Ricevere video](/docs/guides/whatsapp/receiving-whatsapp/video): clip, con una didascalia per cui il ramo audio non ha spazio
- [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)