Skip to content

Voice Note

Also called: Voice message · WhatsApp voice message · Push-to-talk message

Definition
A recorded audio message sent as OGG/Opus and flagged as voice, so WhatsApp plays it as a voice note rather than an attached audio file.

Exhibit A

Voice note or audio file: what changes?

8 / 8

Voice note

type audio, voice: true

Audio file

type audio, voice omitted or false

  1. Voice noteOgg with the Opus codec, mono only
    Audio fileAAC, AMR, MP3, M4A or OGG/Opus
  2. Voice notePlay icon only at 512 KB or less
    Audio fileUp to 16 MB
  3. Voice noteProfile picture, microphone icon, inline play
    Audio fileMusic icon; the customer taps to download
  4. Voice noteAutomatic
    Audio fileManual
  5. Voice notePer the user's transcription setting
    Audio fileNot for most formats; OGG/Opus can still be transcribed
  6. Voice notetype audio, voice: true
    Audio filetype audio, voice: false
  7. Voice noteplayed status when first played
    Audio filedelivered and read only

Verdict

Use a voice note for a spoken reply the customer should hear at once; use an audio file for recordings they may keep or forward, such as a recorded announcement.

The same audio message type behaves two ways depending on one flag and the file's format. Compare how each is sent, shown in the chat and reported back by webhook.

Verdict: Use a voice note for a spoken reply the customer should hear at once; use an audio file for recordings they may keep or forward, such as a recorded announcement.

What is a WhatsApp voice note?

A voice note, which WhatsApp calls a voice message, is a recorded audio clip that the app shows with the sender's profile picture, a microphone icon and an inline play bar, and that downloads automatically. On the WhatsApp Cloud API it is not a separate message type: it is an audio message with the voice flag set to true, which tells WhatsApp to present the file as a voice recording instead of a generic audio attachment with a music icon that the user must tap to download.

The format is strict. Voice messages must be .ogg files encoded with the Opus codec, and only mono input is supported; Ogg audio in another codec is not accepted, and a MIME type that does not match the file is the most common error. The play icon appears only when the file is 512 KB or smaller; above that, WhatsApp shows a download icon. Ordinary audio files (AAC, AMR, MP3, M4A or OGG/Opus) can be up to 16 MB. Depending on the user's own settings, WhatsApp may also show a transcript of a voice message on their phone.

In the other direction, a customer's voice note reaches your webhook as a message of type audio whose audio object holds a media id, a mime_type such as audio/ogg; codecs=opus, a sha256 hash and voice: true; false means the customer attached an audio file instead. The API does not transcribe it for you — turning it into text is a speech-to-text job. And a voice note has nothing to do with calling: the WhatsApp Business Calling API carries live calls, not recorded messages.

Key takeaways

  • A voice note is an audio message WhatsApp shows as a recorded voice message, with a microphone icon and inline play, rather than as a file to download.
  • To send one, use an .ogg file encoded with Opus in mono and set audio.voice to true in the message.
  • The inline play icon appears only for files of 512 KB or less; larger files show a download icon instead.
  • Inbound voice notes arrive as type: audio with audio.voice: true and a media ID that expires after 7 days.
  • A played status webhook tells you when the customer first plays a voice note you sent.

A WhatsApp voice note in code

# 1. Convert any recording to the voice-note format: Ogg container, Opus codec, mono
ffmpeg -i reply.wav -c:a libopus -b:a 24k -ac 1 -ar 48000 reply.ogg
 
# 2. Upload it — the response is {"id": "<MEDIA_ID>"}
curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/media" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -F messaging_product=whatsapp \
  -F type=audio/ogg \
  -F "file=@reply.ogg;type=audio/ogg"
 
# 3. Send it as a voice note
curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "919812345678",
    "type": "audio",
    "audio": { "id": "{MEDIA_ID}", "voice": true }
  }'

Without "voice": true the same file arrives as an audio attachment.

How does a WhatsApp voice note work?

  1. Encode as OGG/Opus mono

    Record or synthesise the reply, then transcode to an Ogg container with the Opus codec and one channel. At a speech bitrate of 24 kbps, 512 KB holds close to three minutes, so short replies fit easily.

  2. Upload it

    POST the file to /{PHONE_NUMBER_ID}/media with type audio/ogg to get a media ID, or host it and send a link. Make the MIME type match the file.

  3. Send with voice: true

    Send type: audio with audio: { id, voice: true }. As a free-form message it needs an open customer service window.

  4. Receive customers' voice notes

    The webhook brings type: audio with voice: true. Exchange the media ID for a download URL (valid for 5 minutes) and fetch the file with your access token, well within the ID's 7-day life.

  5. Track playback

    For voice notes you send, a status webhook with status: played arrives the first time the customer's device plays it, separate from delivered and read.

Example: Tamil voice orders at a Coimbatore pharmacy

Many of a Coimbatore pharmacy's older customers order by sending a Tamil voice note listing their regular medicines. The webhook handler sees voice: true, downloads the file within seconds, and passes it to speech-to-text and then to a pharmacist, who checks the list against the customer's past orders. The pharmacist replies with a 40-second Tamil voice note confirming the items and the pickup time, encoded as OGG/Opus mono at about 120 KB and sent with voice: true, followed by a short text summary. A played status a few minutes later confirms the customer listened; when none arrives within two hours, an agent follows up by text.

Common mistakes with a WhatsApp voice note

  • Forgetting the voice flag

    Without voice: true, even a perfect OGG/Opus file can arrive as an audio attachment the customer must tap to download. Set the flag on every voice reply.

  • The wrong codec or stereo

    An MP3 renamed to .ogg, Ogg Vorbis or a stereo file is not a valid voice message. Transcode with an Opus encoder to one channel and send a MIME type that matches the file.

  • Files over 512 KB

    A long or high-bitrate recording loses the inline play icon and shows a download icon instead. Keep business voice notes short and encode speech at a low bitrate.

  • Answering voice with "please type"

    Customers who send voice notes often cannot or will not type. Transcribe them, or route them to an agent who can listen, instead of asking for text.

  • Letting media expire

    A media ID from a webhook works for 7 days and each download URL for 5 minutes. Download inbound voice notes as they arrive, not when an agent finally opens the chat.

Best practices for a WhatsApp voice note

  • Keep business voice notes under a minute and say the key fact first.
  • Send a short text summary with important voice notes, for customers who cannot play audio right now.
  • Use the played status, not read, to know a voice note was actually heard.
  • Normalise loudness before encoding so replies are audible on a phone speaker.

Why does a WhatsApp voice note matter?

Voice notes are how a large share of Indian customers prefer to talk to a business: faster than typing, easier in their own language, natural for people less comfortable with text. A business that can receive them, route them and sometimes answer with a short voice note of its own feels conversational; one that replies "please type your message" loses the customer. Getting the voice flag and the format right is the difference between a reply that plays at once like a person's and a file nobody opens.

Voice Note FAQs

How do I send a voice note with the WhatsApp Cloud API?+
Send an `audio` message with `voice` set to `true`, using an `.ogg` file encoded with Opus in mono. Upload the file to get a media ID (or send a link), keep it at 512 KB or less so it shows the play icon, and send it inside an open customer service window.
Why does my WhatsApp audio show as a file instead of a voice message?+
Usually the `voice` flag is missing or the file is not OGG/Opus mono. Set `audio.voice: true`, transcode to Opus with one channel, make sure the MIME type matches the file, and keep it at 512 KB or smaller so the play icon appears.
How can I tell a voice note from an audio file in the webhook?+
Check `audio.voice`. It is `true` when the customer recorded the clip with WhatsApp's voice-recording feature and `false` when they attached an existing audio file; both arrive as `type: audio`.
Does WhatsApp transcribe voice notes for businesses?+
Not through the API. A customer's WhatsApp app may show a transcript of voice messages, depending on their settings, but your webhook receives only the audio, so transcription needs your own speech-to-text step.
Can I tell whether a customer listened to my voice note?+
Yes. A status webhook with `status: played` arrives the first time the customer's device plays a voice message you sent. It is separate from the `read` status, which only means the chat was opened.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms