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

Esempio di codice

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

Esempio di codice

{
  "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: l'envelope in entrata, il download dei media e il webhook whatsapp.received
Messaggi audio WhatsApp: il lato invio dello stesso ramo
Ricevere video: clip, con una didascalia per cui il ramo audio non ha spazio
Eventi WhatsApp: l'elenco completo degli eventi, tramite API o webhook

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channel Comprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builder Esplora la funzionalitàWhatsApp

Prova l'esercitazione e ottieni un brief di implementazione