Voice Transcription
Voice notes can be transcribed automatically. When a message with a voice recording is sent to a channel that has voice transcription turned on, Stream converts the speech to text in the background and stores the text on the recording's attachment. Clients receive it through a message.updated event, and it is part of the message in every later read.
Voice transcription is in beta. Stream enables it per app: contact support to turn it on.
Transcripts let people read a voice note when they can't play audio, and make voice notes accessible to users who are deaf or hard of hearing.
How it works
-
A user sends a message with a
voiceRecordingattachment. Stream's iOS, Android, React Native and React SDKs send recorded voice notes this way. The attachment needs anasset_url, usually the URL of a file uploaded to Stream. -
The message is delivered right away, as usual, without a transcript.
-
Stream transcribes the recording in the background. The transcript usually arrives shortly after the message itself.
-
The transcript is saved on the attachment as
voice_transcript, and amessage.updatedevent is sent to the channel (and to your webhooks) with the updated message. This event does not send a push notification.
Each voice recording in a message is transcribed separately. Messages in threads are transcribed like any other message.
Enabling voice transcription
Voice transcription is off by default. Two settings must both be on:
-
For your app. Voice transcription has to be enabled for your app by Stream. Contact support to turn it on.
-
For the channel type. Set
voice_transcriptiontotrueon each channel type whose voice notes you want transcribed. It isfalsefor every built-in channel type.
await client.chat.updateChannelType({
name: "messaging",
voice_transcription: true,
});Turning it on or off for a single channel
A channel can override the channel type setting in either direction with config_overrides.voice_transcription. For example, keep it off for the channel type and turn it on only for selected channels. See Channel-level settings for how overrides work.
await channel.updateChannelPartial({
set: { config_overrides: { voice_transcription: true } },
});Turning voice transcription on does not transcribe voice notes that are already in the channel. Turning it off also stops transcriptions that are still pending.
The transcript
The transcript is stored in the voice_transcript field of the voice recording attachment. This is how a message with a transcribed voice note looks, for example in the message.updated event or when you query the channel:
{
"id": "4f0c0a62-2f3b-4f6b-9a4d-1b7d5f0f3c21",
"cid": "messaging:general",
"type": "regular",
"text": "",
"user": { "id": "jane", "name": "Jane" },
"created_at": "2026-11-13T09:41:07.123Z",
"updated_at": "2026-11-13T09:41:08.456Z",
"attachments": [
{
"type": "voiceRecording",
"asset_url": "https://us-east.stream-io-cdn.com/.../voice-note.aac",
"mime_type": "audio/aac",
"file_size": 48213,
"duration": 4.2,
"voice_transcript": {
"text": "Running ten minutes late, start without me.",
"languages": [{ "code": "en" }]
}
}
]
}| Field | Type | Description |
|---|---|---|
text |
string | The transcribed text. Left out if the recording could not be transcribed or contains no speech. |
languages |
array | The languages detected in the recording, as objects with a language code (for example en). |
error |
string | Set instead of text when the recording could not be transcribed. See Errors below. |
An attachment without a voice_transcript field has not been transcribed yet, or transcription is not enabled for its channel.
To show transcripts in your app, read voice_transcript from the voice recording attachment when you render the message, and re-render when the message.updated event for that message arrives.
Errors
When a recording can't be transcribed, voice_transcript.error is set to one of these values. The message still gets a message.updated event, so your UI can stop waiting for a transcript.
| Error | Meaning |
|---|---|
unsupported_format |
The audio could not be decoded. |
too_large |
The recording is larger than 25 MiB. |
fetch_failed |
The file could not be downloaded from its asset_url, for example because the file was deleted or access to it was denied. |
invalid_response |
The speech-to-text service returned a result that could not be used. |
These errors are final for that recording. Treat any other error value the same way, as a recording that could not be transcribed. Temporary problems, such as network errors or an outage of the file host or the speech-to-text service, are retried automatically and are not stored as errors. If the retries also fail, the attachment is left without a voice_transcript.
Messages that are not transcribed
- Attachments of any type other than
voiceRecording, and voice recordings without anasset_url. - Messages in channels where voice transcription is off.
- Deleted messages, including messages deleted before their transcription finished.
- Messages that are not of type
regularorreply, for example messages blocked by moderation, system messages and error messages.
Editing messages
The transcript is managed by Stream. Clients can't set or change it: a voice_transcript sent in a request is ignored.
When a message is edited and the voice recording stays the same file, the transcript is kept, even though clients send the attachment back without it or with a newly signed asset_url. If the edit replaces the recording with a different file, the new file is transcribed.
If you already store your own transcript in a custom attachment field such as transcript, it is not affected.
Supported formats and limits
- Recordings can be up to 25 MiB.
- The AAC voice notes recorded by Stream's iOS, Android and React Native SDKs are supported, as are common audio formats such as M4A, MP4, MP3, WAV, WebM, OGG and FLAC.
- The language is detected automatically. You don't need to set a language on the user or the channel.
- Transcription is not limited to a fixed list of languages. Stream does not restrict which languages are transcribed.
Exports and usage
Channel exports include voice_transcript on voice recording attachments.
Voice transcription usage is measured in seconds of transcribed audio and reported as transcription_seconds. Each recording is rounded up to the next whole second.