Skip to navigation
API ReferenceVoice Agent

Build a Voice Agent

Build a conversational voice agent using Deepgram's Voice Agent WebSocket

HandshakeTry it

WSS
wss://agent.deepgram.com/v1/agent/converse

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 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%

Send

AgentV1SettingsobjectRequired
Send settings configuration to Deepgram's Voice Agent API
OR
AgentV1UpdateListenobjectRequired
Send update listen to Deepgram's Voice Agent API
OR
AgentV1UpdateThinkobjectRequired
Send update think to Deepgram's Voice Agent API
OR
AgentV1UpdateThinkLiveobjectRequired
Send an update to the Think Live model configuration to Deepgram's Voice Agent API
OR
AgentV1UpdateSpeakobjectRequired
Send update speak to Deepgram's Voice Agent API
OR
AgentV1InjectUserMessageobjectRequired
Send inject user message to Deepgram's Voice Agent API
OR
AgentV1InjectAgentMessageobjectRequired
Send inject agent message to Deepgram's Voice Agent API
OR
AgentV1InjectDynamicAgentMessageobjectRequired
Send a dynamic inject agent message to Deepgram's Voice Agent API, letting the Think Live model generate the filler line
OR
AgentV1SendFunctionCallResponseobjectRequired

Send a function call response from the client to the server after executing a client-side function call. This is used when the server requests execution of a function marked with client_side: true.

OR
AgentV1KeepAliveobjectRequired
Send keep alive to Deepgram's Voice Agent API
OR
AgentV1UpdatePromptobjectRequired
Send a prompt update to Deepgram's Voice Agent API
OR
AgentV1ForceEndTurnobjectRequired
Send a ForceEndTurn message to immediately end the current user turn
OR
AgentV1CustomToThinkProviderobjectRequired

Experimental. Send an arbitrary JSON payload to a custom think provider. Requires a wss:// custom Think endpoint in agent.think.endpoint.url.

OR
AgentV1MediastringRequiredformat: "binary"
Send raw binary audio data to Deepgram's Voice Agent API for processing

Receive

AgentV1ListenUpdatedobjectRequired
Receive listen update from Deepgram's Voice Agent API
OR
AgentV1ThinkUpdatedobjectRequired
Receive think update from Deepgram's Voice Agent API
OR
AgentV1ThinkLiveUpdatedobjectRequired
Receive Think Live model update confirmation from Deepgram's Voice Agent API
OR
AgentV1FrustrationDetectedobjectRequired
Receive a frustration detection event from Deepgram's Voice Agent API
OR
AgentV1ReceiveFunctionCallResponseobjectRequired

Receive a function call response from the server after the server has executed a server-side function call internally. This occurs when functions are marked with client_side: false.

OR
AgentV1PromptUpdatedobjectRequired
Receive prompt update from Deepgram's Voice Agent API
OR
AgentV1SpeakUpdatedobjectRequired
Receive speak update from Deepgram's Voice Agent API
OR
AgentV1InjectionRefusedobjectRequired
Receive injection refused message from Deepgram's Voice Agent API
OR
AgentV1WelcomeobjectRequired
Receive welcome message from Deepgram's Voice Agent API
OR
AgentV1SettingsAppliedobjectRequired
Receive settings applied message from Deepgram's Voice Agent API
OR
AgentV1ConversationTextobjectRequired
Receive conversation text from Deepgram's Voice Agent API
OR
AgentV1UserStartedSpeakingobjectRequired
Receive user started speaking message from Deepgram's Voice Agent API
OR
AgentV1AgentThinkingobjectRequired
Receive agent thinking message from Deepgram's Voice Agent API
OR
AgentV1LatencyReportobjectRequired
Receive a latency report from Deepgram's Voice Agent API
OR
AgentV1FunctionCallRequestobjectRequired
Receive function call request from Deepgram's Voice Agent API
OR
AgentV1FunctionCallCancelledobjectRequired
Receive notice that a function call you already received was cancelled because the user started speaking again
OR
AgentV1AgentStartedSpeakingobjectRequired
Receive agent started speaking message from Deepgram's Voice Agent API
OR
AgentV1AgentAudioDoneobjectRequired
Receive agent audio done message from Deepgram's Voice Agent API
OR
AgentV1CustomFromThinkProviderobjectRequired

Experimental. Receive a response body from a custom think provider, passed through unchanged. Requires a wss:// custom Think endpoint in agent.think.endpoint.url.

OR
AgentV1ErrorobjectRequired
Receive error response from Deepgram's Voice Agent API
OR
AgentV1WarningobjectRequired
Receive warning messages from Deepgram's Voice Agent API
OR
AgentV1HistoryobjectRequired

Receive a conversation history message from Deepgram’s Voice Agent API. Each message is either a conversation text (with role and content) or a function call record (with function_calls array).

OR
AgentV1AudiostringRequiredformat: "binary"
Receive raw binary audio data generated by Deepgram's Voice Agent API