Voice Agent API Migration Guide
Guide for migrating from Voice Agent API Early Access to V1.
This guide helps developers migrate from the early access version of the Deepgram Voice Agent API to the official V1 release.
The Deepgram API Spec and Voice Agent API Reference have more details on the new Voice Agent API.
Endpoint Changes
Message Type Changes
Removed Message Types
The following message types from early access have been removed in V1:
New Message Types
Here is a list of all-new message types in V1:
Welcome
Message Changes
The welcome message has had the session_id
field renamed to request_id
to better align with other products.
Early Access: Welcome
V1: Welcome
SettingsConfiguration
Becomes Settings
The most significant change is to the configuration message:
Early Access: SettingsConfiguration
V1: Settings
For more details on all the possible settings available in the new Settings
message, check out the Configure the Voice Agent guide.
Key differences:
- Message type changed from
SettingsConfiguration
toSettings
- Added fields:
mip_opt_out
andexperimental
- Introduced provider-based structure for listen, think, and speak capabilities
instructions
field renamed toprompt
in the think configuration- Added
container
field to audio output configuration - Added optional
greeting
field - Added support for custom endpoints via the
endpoint
object for non-Deepgram providers
UpdateSpeak
Changes
The UpdateSpeak
message has been restructured to use the provider pattern:
Early Access: UpdateSpeak
V1: UpdateSpeak
InjectAgentMessage
Changes
The InjectAgentMessage
message has a field rename:
Early Access: InjectAgentMessage
V1: InjectAgentMessage
Function Calling Changes
The function calling interface has significant changes:
Early Access: FunctionCallRequest
V1: FunctionCallRequest
Early Access: FunctionCallResponse
V1: FunctionCallResponse
Error
Response Changes
The Error
message structure has been updated:
Early Access: Error
V1: Error
Function Call Handling in V1
The function calling system in V1 has been significantly improved with a clearer client-side vs. internal server-side execution model.
FunctionCallRequest
In V1, the FunctionCallRequest
message includes a client_side
flag that explicitly indicates where the function should be executed:
When handling a FunctionCallRequest
:
- Check the
client_side
flag in each function - If
client_side
istrue
, your client code must:- Execute the specified function with the provided arguments
- Send a
FunctionCallResponse
back to the server
- If
client_side
isfalse
, no client action is needed as the server will handle it internally
FunctionCallResponse
The FunctionCallResponse
message has been updated to include the function name and uses clearer field names:
Key points about FunctionCallResponse
:
- It can be sent by either the client or the server depending on where the function was executed
- The
id
field links the response to the original request - The
name
field identifies which function was called - The
content
field contains the function result, often in JSON format
Implementation Tips
When migrating your function calling implementation:
- Update your client code to check the
client_side
flag - Only respond to functions where
client_side
istrue
- Use the
id
field to track which request you’re responding to - Include both the function
name
andcontent
in your response - Expect the server to send you
FunctionCallResponse
messages for functions withclient_side: false
Migration Checklist
- ✅ Update WebSocket endpoint URL
- ✅ Update configuration message format
- Rename
SettingsConfiguration
toSettings
- Add provider objects for listen, think, and speak
- Change
instructions
toprompt
- Use specific model identifiers
- Rename
- ✅ Update function calling implementation
- Adapt to new request/response formats
- Implement client_side flag handling
- ✅ Handle error messages with new format
- Use
description
instead ofmessage
- Process error codes
- Use
- ✅ Implement support for new message types
- Handle
PromptUpdated
andSpeakUpdated
confirmations - Process
Warning
messages
- Handle
- ✅ Update the
InjectAgentMessage
format- Change
message
field tocontent
- Change
- ✅ Handle welcome messages with
request_id
instead ofsession_id
Common Migration Issues
- Configuration not accepted: Make sure you’ve updated to the provider-based structure for capabilities
- Function calls not working: Update both the request and response formats to match V1 specifications
- Error handling failures: Update error handling to use
description
instead ofmessage
- Cannot inject messages: Use
content
instead ofmessage
inInjectAgentMessage
- Missing confirmation messages: Implement handlers for the new confirmation message types
New Capabilities in V1
- Multi-provider support: Configure different providers for listen, think, and speak capabilities
- Greeting messages: Set an initial greeting via the
greeting
field - Improved error handling: Structured errors with codes for better diagnostics
- Client-side function execution: Control whether functions run client-side or server-side
- Warnings: Non-fatal issues are now reported via Warning messages