For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Ask AIPlaygroundLoginFree API Key
HomeAPI ReferenceVoice AgentSpeech-to-TextText-to-SpeechIntelligenceSelf-Hosted Deployments
HomeAPI ReferenceVoice AgentSpeech-to-TextText-to-SpeechIntelligenceSelf-Hosted Deployments
  • General
    • Deepgram API Overview
    • Authentication
    • Regional Endpoints
    • Custom Endpoints
    • Errors
    • API Rate Limits
  • API Reference
        • WSSLive Audio
        • POSTPre-Recorded Audio
        • WSSTurn-based Audio (Flux)
LogoLogo
Ask AIPlaygroundLoginFree API Key
API ReferenceSpeech to Text

Turn-based Audio (Flux)

WSS
wss://api.deepgram.com/v2/listen
Handshake
URLwss://api.deepgram.com/v2/listen
MethodGET
Status101 Switching Protocols
Try it
Messages

Real-time conversational speech recognition with contextual turn detection for natural voice conversations

Was this page helpful?
Previous

Continuous Text Stream

Next
Built with

HandshakeTry it

WSS
wss://api.deepgram.com/v2/listen

Authentication

AuthorizationToken

Use Authorization: Token <API_KEY> Example: Authorization: Token 12345abcdef

OR
AuthorizationBearer

Use Authorization: Bearer <JWT> Example: Authorization: Bearer eyJhbGciOiJ...

Headers

AuthorizationstringRequired
Use your API key or a [temporary token](/guides/fundamentals/token-based-authentication) for authentication via the `Authorization` header. In client-side environments where custom headers are not supported, use the [`Sec-WebSocket-Protocol`](/guides/deep-dives/using-the-sec-websocket-protocol) header instead. **Example:** `Authorization: Token %DEEPGRAM_API_KEY%` or `Authorization: Bearer %DEEPGRAM_TOKEN%`

Query parameters

modelenumRequired
Defines the AI model used to process submitted audio.
Allowed values:
encodingenumOptional

Encoding of the audio stream. Required if sending non-containerized/raw audio. If sending containerized audio, this parameter should be omitted.

sample_rateanyOptional

Sample rate of the audio stream in Hz. Required if sending non-containerized/raw audio. If sending containerized audio, this parameter should be omitted.

eager_eot_thresholdanyOptional

End-of-turn confidence required to fire an eager end-of-turn event. When set, enables EagerEndOfTurn and TurnResumed events. Valid Values 0.3 - 0.9.

eot_thresholdanyOptionalDefaults to 0.7

End-of-turn confidence required to finish a turn. Valid Values 0.5 - 0.9.

eot_timeout_msanyOptionalDefaults to 5000
A turn will be finished when this much time has passed after speech, regardless of EOT confidence.
keytermstring or list of stringsOptional
Keyterm prompting can improve recognition of specialized terminology. Pass multiple keyterm query parameters to boost multiple keyterms.
language_hintstring or list of stringsOptional

Language hints constrain and prioritize language detection for the flux-general-multi model. Pass multiple language_hint query parameters to specify multiple language codes. Empty values are rejected. Only valid when model is flux-general-multi.

profanity_filterenumOptionalDefaults to false

Profanity Filter looks for recognized profanity and converts it to the nearest recognized non-profane word or removes it from the transcript completely.

Allowed values:
mip_opt_outanyOptional
Opts out requests from the Deepgram Model Improvement Program. Refer to our Docs for pricing impacts before setting this to true. https://dpgr.am/deepgram-mip
taganyOptional
Label your requests for the purpose of identification during usage reporting

Send

ListenV2MediastringRequiredformat: "binary"
Send audio or video data to be transcribed
OR
ListenV2CloseStreamobjectRequired
Send a CloseStream message to close the WebSocket stream
OR
ListenV2ConfigureobjectRequired
Send a Configure message to update Flux settings

Receive

ListenV2ConnectedobjectRequired
Receive a connected message
OR
ListenV2TurnInfoobjectRequired
Receive a turn info message
OR
ListenV2ConfigureSuccessobjectRequired

Sent when a Configure message was successfully applied. Returns the current, up-to-date values that were applied.

OR
ListenV2ConfigureFailureobjectRequired
Indicates that a Configure message was rejected
OR
ListenV2FatalErrorobjectRequired
Receive a fatal error message

Use your API key or a temporary token for authentication via the Authorization header. In client-side environments where custom headers are not supported, use the Sec-WebSocket-Protocol header instead.

Example: Authorization: Token %DEEPGRAM_API_KEY% or Authorization: Bearer %DEEPGRAM_TOKEN%

Opts out requests from the Deepgram Model Improvement Program. Refer to our Docs for pricing impacts before setting this to true. https://dpgr.am/deepgram-mip