# Audio messages | Developer Documentation

<div id="bkmrk-audio-messagesupdate">## Audio messages

<div><span>Updated: Feb 17, 2026</span></div><div><span></span><div>On March 17th, 2026, voice messages will start receiving a [“played” status webhook](/books/meta-whatsapp/page/status-messages-webhook-reference-developer-documentation) the first time a WhatsApp user plays a voice message shared by the business.</div></div><div>You can use Cloud API to send voice messages and basic audio messages.</div><div id="bkmrk-voice-messages"><div id="bkmrk-voice-messages-1"><div>### Voice messages

</div></div></div><div>A voice message (sometimes referred to as a voice note, voice memo, or audio) is a recording of one or more persons speaking, and can include background sounds like music. Voice messages include features like automatic download, profile picture, and voice icon. These features are not available with basic audio messages. If the user sets voice message transcripts to **Automatic**, the message includes a text transcription.</div><div>![](https://support2.chatarchitect.com/uploads/images/gallery/2026-04/embedded-image-9jw48xtf.png)</div>
<span>Voice messages require .ogg files encoded with the **OPUS** codec. If you send a different file type or a file encoded with a different codec, voice message transcription will fail.</span><span>The play icon will only appear if the file is 512KB or smaller, otherwise it will be replaced with a download icon (a downward facing arrow).</span><span>The message displays your business’s profile image with a microphone icon.</span><span>The text transcription appears if the user has enabled **Automatic** [voice message transcripts<span>⁠</span>](https://l.facebook.com/l.php?u=https%3A%2F%2Ffaq.whatsapp.com%2F241617298315321%2F&h=AT5XzkCq7R5XP1Y2pGGxquqnT2xcoEVddM6jrUyH_7XDbF0NyYJHCrG7AoVhyVCr9zkCtBexFgJN9OOfpahqOqUcchcILl1JqllxFAq8BJUQkD_Vr-6zDjuHKqzNAxDtTNQbW0xI8pJVbL_dAJ_Q5A). If the user has set this to **Manual**, the text “Transcribe” will appear instead, which will display the transcribed text once tapped. If the user has set voice message transcripts to **Never**, no text will appear.</span><div id="bkmrk-basic-audio-messages"><div id="bkmrk-basic-audio-messages-1"><div>### Basic audio messages

</div></div></div><div>Basic audio messages display a download icon and a music icon. When the WhatsApp user taps the play icon, the user manually download the audio message for the WhatsApp client to load and then play the audio file.</div><div>![](https://support2.chatarchitect.com/uploads/images/gallery/2026-04/embedded-image-mxrmswwk.png)</div>
<span>The download icon will be replaced with a play icon if the WhatsApp user has enabled [auto-download<span>⁠</span>](https://l.facebook.com/l.php?u=https%3A%2F%2Ffaq.whatsapp.com%2F366146522333492%2F&h=AT5XzkCq7R5XP1Y2pGGxquqnT2xcoEVddM6jrUyH_7XDbF0NyYJHCrG7AoVhyVCr9zkCtBexFgJN9OOfpahqOqUcchcILl1JqllxFAq8BJUQkD_Vr-6zDjuHKqzNAxDtTNQbW0xI8pJVbL_dAJ_Q5A) for audio media and conditions for auto-download are met (e.g. connected to wi-fi).</span><span>If you send a .ogg file encoded with the OPUS code as a basic audio message, the music icon will be replaced with a microphone icon. In addition, if the user has enabled **Automatic** or **Manual** [voice message transcripts<span>⁠</span>](https://l.facebook.com/l.php?u=https%3A%2F%2Ffaq.whatsapp.com%2F241617298315321%2F&h=AT5XzkCq7R5XP1Y2pGGxquqnT2xcoEVddM6jrUyH_7XDbF0NyYJHCrG7AoVhyVCr9zkCtBexFgJN9OOfpahqOqUcchcILl1JqllxFAq8BJUQkD_Vr-6zDjuHKqzNAxDtTNQbW0xI8pJVbL_dAJ_Q5A), a text transcription or the text “Transcribe” will accompany the message.</span><div id="bkmrk-request-parameters"><div id="bkmrk-request-parameters-1"><div>### Request parameters

</div></div></div><div><table><thead><tr><th><span>Placeholder </span></th><th><span>Description </span></th><th><span>Example Value </span></th></tr></thead><tbody><tr><td><div><div>`<ACCESS_TOKEN>`</div><div>*String*</div></div></td><td><div><div>**Required.**</div><div>[System token](/books/meta-whatsapp/page/access-tokens-guide-developer-documentation) or [business token](/books/meta-whatsapp/page/access-tokens-guide-developer-documentation).</div></div></td><td><div><div>```
EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD
```

</div></div></td></tr><tr><td><div><div>`<API_VERSION>`</div><div>*String*</div></div></td><td><div><div>**Optional.**</div><div>Graph API version.</div></div></td><td><div><div>v25.0</div></div></td></tr><tr><td><div><div>`<IS_VOICE?>`</div><div>*Boolean*</div></div></td><td><div><div>**Optional.**</div><div>Set to `true` if sending a [voice message](#bkmrk-voice-messages-1). Voice messages must be Ogg files encoded with the **OPUS** codec.</div><div>To send a [basic audio message](#bkmrk-basic-audio-messages-1), set to `false` or omit entirely.</div></div></td><td><div><div>`true`</div></div></td></tr><tr><td><div><div>`<MEDIA_ID>`</div><div>*String*</div></div></td><td><div><div>**Required if using uploaded media, otherwise omit.**</div><div>ID of the [uploaded media asset](/books/meta-whatsapp/page/media-developer-documentation).</div></div></td><td><div><div>`1013859600285441`</div></div></td></tr><tr><td><div><div>`<MEDIA_URL>`</div><div>*String*</div></div></td><td><div><div>**Required if using hosted media, otherwise omit.**</div><div>URL of the media asset hosted on your public server. For better performance, we recommend using `id` and an [uploaded media asset ID](/books/meta-whatsapp/page/media-developer-documentation) instead.</div></div></td><td><div><div>`https://www.luckyshrub.com/media/ringtones/wind-chime.mp3`</div></div></td></tr><tr><td><div><div>`<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>`</div><div>*String*</div></div></td><td><div><div>**Required.**</div><div>WhatsApp business phone number ID.</div></div></td><td><div><div>`106540352242922`</div></div></td></tr><tr><td><div><div>`<WHATSAPP_USER_PHONE_NUMBER>`</div><div>*String*</div></div></td><td><div><div>**Required.**</div><div>WhatsApp user phone number.</div></div></td><td><div><div>`+16505551234`</div></div></td></tr></tbody></table>

</div><div id="bkmrk-supported-audio-form"><div id="bkmrk-supported-audio-form-1"><div>### Supported audio formats

</div></div></div><div><table><thead><tr><th><span>Audio Type </span></th><th><span>Extension </span></th><th><span>MIME Type </span></th><th><span>Max Size </span></th></tr></thead><tbody><tr><td><div><div>AAC</div></div></td><td><div><div>.aac</div></div></td><td><div><div>audio/aac</div></div></td><td><div><div>16 MB</div></div></td></tr><tr><td><div><div>AMR</div></div></td><td><div><div>.amr</div></div></td><td><div><div>audio/amr</div></div></td><td><div><div>16 MB</div></div></td></tr><tr><td><div><div>MP3</div></div></td><td><div><div>.mp3</div></div></td><td><div><div>audio/mpeg</div></div></td><td><div><div>16 MB</div></div></td></tr><tr><td><div><div>MP4 Audio</div></div></td><td><div><div>.m4a</div></div></td><td><div><div>audio/mp4</div></div></td><td><div><div>16 MB</div></div></td></tr><tr><td><div><div>OGG Audio</div></div></td><td><div><div>.ogg</div></div></td><td><div><div>audio/ogg (OPUS codecs only; base audio/ogg not supported; mono input only)</div></div></td><td><div><div>16 MB</div></div></td></tr></tbody></table>

</div><div>The most common errors associated with audio files are mismatched MIME types (MIME type doesn’t match the file type indicated by the file name) and invalid encoding for Ogg files (OPUS codec only). If you encounter an error when sending a media file, verify that your audio file’s MIME type matches its extension and is a supported type. For Ogg files, use the OPUS codec for encoding.</div></div>