Guides
Voice Messages: What a Persona Hears
What a Persona hears in a voice message, what she does with it, and the limits a recording has to fit.
Overview
Some Users talk instead of typing. Give us the recording and the Persona answers it like a person would.
We fetch the file, transcribe what was said, and describe how it sounded: the delivery, the emotional colour of the voice, whether someone else is in the room, what is audible behind them. The Persona then replies to what was said and to how it was said — the part a transcript alone throws away.
Three things to know before you read further:
- Inbound only. We understand the voice messages a User sends. The Persona never sends one back.
- Off until you switch it on. Turn on the Audio switch in your settings, or set
replyParameters.audio.sharedAudiosAnalysison a request. Once it is on, a message that carriesaudioUrlsis analyzed, and you are billed for it. - The Persona never pretends to have heard something. A recording we could not use is said to be unheard, in her own words, rather than guessed at.
Availability
Every chat model hears voice messages in full. See Model Versions.
When Analysis Is Off
With audio analysis off, a voice message is never listened to and never billed. The Persona is told the User sent one that she has no way to play, and she says so plainly, in her own words, without guessing at what was said. Only the latest such message asks her to say so, and it asks again on every reply while it is still in the history we read, so she may say it more than once. A voice message that also carries text is answered from that text.
What the Persona Is Told
She is told that the message was spoken, then what the analysis heard.
| What she gets | Example of what it carries |
|---|---|
| The words | The transcript, in the language it was spoken in. We never translate it. |
| What the audio mostly is | Speech, singing, music, background noise, silence, or a mix of them. |
| How the voice is used | Normal, whispered, shouted, sung, guttural, distorted, robotic. |
| The tone of the delivery | Neutral, jovial, excited, flirtatious, sad, angry, anxious, tired, flat. |
| Whether it sounds unusual | Growled, pitch-shifted, heavily processed, played through a speaker. |
| Whether the User was alone | Alone, someone with them and part of the exchange, or other voices around them. |
| A notable accent | Named plainly, and only when there is something worth naming. |
| What is audible behind them | Music, a street, a television, a room. |
| How well it could be heard | Whether parts were hard to make out. |
Limits a Recording Has to Fit
| Limit | Value |
|---|---|
| Length | 90 seconds. A longer recording, or one whose length we cannot measure, is not listened to at all. |
| Size | 15 MB. A larger file is refused before we finish downloading it. |
| Formats | wav, mp3, m4a, mp4, aac, ogg, opus, webm, flac, caf |
| Per message | The first URL only. Put one voice message on one chat history message. |
Every URL must be publicly reachable at the moment we generate the answer, HTTPS strongly recommended. Signed URLs are fine as long as they are still valid when we fetch them.
When a Recording Cannot Be Used
None of these break the reply. She answers, and she is honest about what she got.
| What happened | What the Persona does |
|---|---|
| Nothing on the recording — a muted, unplugged or denied mic | Says lightly that she got it but heard nothing, that their mic looks off, and asks for another one. |
| Longer than 90 seconds | Says briefly that she could not listen to it, without giving a reason or asking for another one. She never implies she heard any part of it. The 90-second limit is yours to enforce in your app. |
| Too noisy to make out | Reacts to how it sounded and says she could not catch the words. |
| Spoken in a language she does not have | Reacts to how it sounded. She is never shown the words, and never hints at what they meant. |
| We could not fetch or analyze it | Says plainly that she cannot play it, then carries on. She never guesses at what was said. |
Pricing
Base cost: €0.015 for every 30 seconds of recording started.
| Length of the recording | Billed as | Cost |
|---|---|---|
| Up to 30 seconds | 1 × 30 seconds | €0.015 |
| Over 30, up to 60 seconds | 2 × 30 seconds | €0.030 |
| Over 60, up to 90 seconds | 3 × 30 seconds | €0.045 |
| Over 90 seconds | Not listened to | Free |
- We key an analysis by URL. The same URL is analyzed once and billed once, however many conversations or projects it appears in, and the result is kept for up to a week.
- Change the file behind a URL and it is a new recording. Fresh analysis, and you pay again.
- A recording with no signal at all is free. We recognise it from the audio itself and never ask a model, so there is nothing to charge for.
- A recording over 90 seconds is free. We decline to listen rather than analyze an opening.
- A recording whose length we cannot measure is free. We do not analyze it.
- A recording we cannot fetch, or cannot name a format for, is free. No analysis, no charge.
Analyses appear as their own Voice Message Analyses line item on your pricing page and invoices. Volumes come back on the Project Statistics endpoint as audioAnalysisCount and audioAnalysisCost, outside the answer spend. audioAnalysisCount counts 30-second slices, not messages: a 50-second recording counts as 2. A voice message is billed when the reply to it is generated, not when the message arrives.
Technical Implementation
Step 1: Return Voice URLs in Your Chat History
In the Chat History Endpoint you host, add an audioUrls array to the message that carried the recording. It sits alongside text, pictureUrls and videoUrls.
{
"messages": [
{
"id": "msg_1042",
"sender": "USER",
"date": "2026-09-14T10:00:00Z",
"audioUrls": ["https://cdn.example.com/u/1042/note.m4a"],
"audioLevelsDb": { "https://cdn.example.com/u/1042/note.m4a": -14.9 }
}
]
}With the Audio switch on in your settings, that is the whole integration. To decide per request instead, send replyParameters.audio.sharedAudiosAnalysis: true or false on a request wins over the switch, and leaving it out follows the switch.
Keep the message id stable. We analyze a recording once, the first time we write a reply to it, so replaying your history on later turns costs nothing.
Step 2: Send the Measured Level, If You Can
audioLevelsDb holds the loudness of each recording in dBFS, keyed by its URL. It is optional and partial — send what you can measure.
A level you do not send, we measure ourselves, so nothing is lost by omitting it. Sending it saves that round-trip, and both the browser and iOS give the number away while recording.
Step 3: Read the Reply
Nothing about the answer changes. The reply comes back as ordinary text on message, and the Persona never returns audio.
The transcript is treated as User text everywhere else, too: it is what Core Guardian reads, what the moderation checks read, and what gets translated. A User cannot get past your safeguards by speaking instead of typing.
Step 4: Try It Before You Ship
The Playground records a voice message from your browser and sends it exactly as your integration would — same analysis, same cache, same 90-second limit, refusals included. It is the fastest way to hear what a Persona does with a clip before you write any code.
Frequently Asked Questions
Do we have to enable anything?
Yes. Audio analysis is off for a new project. Turn on the Audio switch in your settings, or send replyParameters.audio.sharedAudiosAnalysis: true. Until you do, the Persona tells Users she cannot play their voice messages.
Can the Persona send voice messages back? No. Understanding is inbound only.
The Persona says she can't play a voice message. Why? First check that audio analysis is on for that request. If it is, almost always the URL: no recognisable extension in the path, unreachable when we generated the answer, or over the size limit in Limits a Recording Has to Fit. In all three cases we leave the message as it arrived and she says she cannot play it. Check the extension first.
Do you translate what was said? Never. The transcript is always in the language it was spoken in, and a translated transcript is treated as a failed analysis.
What if the User speaks a language the Persona does not have?
She is told how the recording sounded and is never shown the words. She reacts to the voice without carrying on as though she had understood it. The languages she has are the reply language plus additionalLanguages.
Is a voice message counted in the answer cost? No. It is billed as its own line, when the reply is generated. See Pricing.
We re-sent the same conversation history. Are we billed twice? No. An analysis is keyed by URL and kept for up to a week, and a message we have already stored is not analyzed again.
Can a User slip something past moderation by recording it? No. The transcript becomes the text of the message, and every guardrail reads it as though it had been typed.
Is there a rejection event for voice messages, like chat.image.rejected?
No. Voice messages have no rejection event today. Photos and videos do — see Vision Link.
Can we send several recordings on one message? Only the first is analyzed. Put one recording on one message.