# Messaggi audio WhatsApp Un messaggio audio contiene un URL pubblico che WhatsApp recupera al momento dell'invio. Non ha didascalia e può opzionalmente essere visualizzato come nota vocale. ## Inviare un messaggio audio Imposta `audio.url`: **TypeScript** ```typescript const msg = await bird.whatsapp.send({ to: "+16505551234", from: "+13124495648", audio: { url: "https://cdn.example.com/vm/9f2.ogg" }, }); console.log(msg.id, msg.status); ``` Examples: [TypeScript](/it-it/documentazione/guides/whatsapp/message-types/audio.ts.md) · [Python](/it-it/documentazione/guides/whatsapp/message-types/audio.py.md) · [Go](/it-it/documentazione/guides/whatsapp/message-types/audio.go.md) · [PHP](/it-it/documentazione/guides/whatsapp/message-types/audio.php.md) · [CLI](/it-it/documentazione/guides/whatsapp/message-types/audio.cli.md) · [MCP](/it-it/documentazione/guides/whatsapp/message-types/audio.mcp.md) · [cURL](/it-it/documentazione/guides/whatsapp/message-types/audio.curl.md) La forma completa aggiunge il flag opzionale `voice`, l'unico altro campo di `audio`: ```json { "to": "+16505551234", "from": "+13124495648", "audio": { "url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true } } ``` `audio` non ha affatto il campo `caption`. `from` è obbligatorio su ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird. ## Limiti | Campo | Vincolo | Applicato da | | --------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------- | | Dimensione file | 16 MB | Solo WhatsApp, al fetch (asincrono) | | Formato | AAC, AMR, MP3, M4A oppure OGG con codec OPUS, mono | Solo WhatsApp, al fetch (asincrono) | | `voice: true` | richiede `.ogg`/OPUS, mono; altri formati causano il fallimento della trascrizione | Solo WhatsApp, al fetch (asincrono) | | `caption` | non è un campo valido | Bird, all'accettazione (`422`, rifiuto dello schema) | | `url` | assoluto, `https`, con host, senza spazi grezzi | Bird, all'accettazione (`422`) | Bird controlla la forma dell'URL prima che qualsiasi cosa venga accodata; non verifica la dimensione effettiva del file, il formato o il codec, e non verifica che un invio con `voice: true` sia effettivamente `.ogg`/OPUS. Solo il fetch di WhatsApp al momento dell'invio può farlo. Inviare un `caption` su un messaggio audio non è un errore di lunghezza; il campo non esiste nello schema di questo tipo, quindi fallisce come proprietà non riconosciuta. Consulta le guide dell'hub su [invio di media tramite URL](/docs/guides/whatsapp/message-types#sending-media-by-url) e [quando un media fallisce](/docs/guides/whatsapp/message-types#when-media-fails). ## Leggere un messaggio audio in entrata Un messaggio audio in entrata contiene lo stesso oggetto `audio`, più un `id` e un `mime_type` che Bird ha appreso recuperando il file, e nessun `caption` in nessuna delle due direzioni. Consulta [Ricezione audio WhatsApp](/docs/guides/whatsapp/receiving-whatsapp/audio) per la lettura completa in entrata, il payload `whatsapp.received` e a cosa fare attenzione. ## Limiti e modalità di errore - **La finestra di servizio clienti deve essere aperta.** L'audio è un messaggio di servizio, recapitabile solo all'interno di una finestra aperta; consulta la guida dell'hub sulla [finestra di servizio clienti](/docs/guides/whatsapp/message-types#the-customer-service-window). - **Bird rifiuta `http`; WhatsApp stesso lo recupererebbe.** Consulta la guida dell'hub su [invio di media tramite URL](/docs/guides/whatsapp/message-types#sending-media-by-url) per il controllo completo della forma. - **Un fetch rifiutato viene comunque addebitato.** Consulta la guida dell'hub su [quando un media fallisce](/docs/guides/whatsapp/message-types#when-media-fails). Il testo di rifiuto specifico dell'audio da parte di WhatsApp non è stato misurato in modo indipendente, quindi considera la mappatura come dedotta per simmetria piuttosto che confermata per singola causa. - **Il flag `voice` cambia il modo in cui il client del destinatario visualizza il messaggio, non ciò che Bird valida.** `voice: true` lo visualizza come nota vocale: si scarica automaticamente, mostra un'icona microfono inline e può essere trascritto. Per ottenere questo risultato serve un file `.ogg` codificato con OPUS, mono; qualsiasi altro formato viene comunque inviato, ma la trascrizione fallisce lato destinatario. `voice` ha come valore predefinito `false`. - **La soglia dell'icona di riproduzione e il segnale "played" di WhatsApp non sono esposti da Bird.** WhatsApp documenta un comportamento del client per le note vocali brevi e uno stato di riproduzione, ma Bird non modella nessuno dei due; non costruire un'integrazione che si aspetti di leggere l'uno o l'altro dalla API. - **WhatsApp mantiene in cache un URL recuperato per circa 10 minuti.** Reinviare lo stesso URL all'interno di quella finestra restituisce il primo fetch; varia l'URL per forzarne uno nuovo. ## Prossimi passi - [Messaggi di servizio WhatsApp](/docs/guides/whatsapp/message-types): la finestra di servizio clienti e il modello condiviso da ogni messaggio di servizio - [Video](/docs/guides/whatsapp/message-types/video): per un clip video anziché audio - [Sticker](/docs/guides/whatsapp/message-types/stickers): un altro tipo di media senza campo didascalia - [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): la busta della richiesta, il modello `202` e i tentativi sicuri ## 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)