⚠️ SIP Billing Starts November 10, 2025 - See Ultravox Pricing for details.
Overview
Accounts
Agents
Calls, Messages, Stages
- Calls Overview
- GETList Calls
- GETGet Call
- POSTCreate Call
- DELDelete Call
- GETList Call Messages
- GETList Call Tools
- GETGet Call Recording
- GETList Call Stages
- GETGet Call Stage
- GETList Call Stage Messages
- GETList Call Stage Tools
- GETGet Call Stage Message Audio
- GETList Deleted Calls
- GETGet Deleted Call
- GETList Call Events
- GETGet Sip Logs for a call
- POSTSend Data Message to Call
Corpora, Query, Sources
- Corpus Service (RAG) Overview
- GETList Corpora
- POSTCreate Corpus
- GETGet Corpus
- PATCHUpdate Corpus
- DELDelete Corpus
- POSTQuery Corpus
- GETList Corpus Sources
- POSTCreate Corpus Source
- GETGet Corpus Source
- PATCHUpdate Corpus Source
- DELDelete Corpus Source
- GETList Corpus Source Documents
- GETGet Corpus Source Document
- POSTCreate Corpus File Upload
Tools
Voices
Webhooks
SIP Configuration
⚠️ SIP Billing Starts November 10, 2025 - See Ultravox Pricing for details.
Create Scheduled Call Batch
Creates a new scheduled call batch using the the specified agent
curl --request POST \
--url https://api.ultravox.ai/api/agents/{agent_id}/scheduled_batches \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"calls": [
{
"medium": {
"webRtc": {
"dataMessages": {
"pong": true,
"state": true,
"transcript": true,
"clientToolInvocation": true,
"dataConnectionToolInvocation": true,
"playbackClearBuffer": true,
"callStarted": true,
"debug": true,
"callEvent": true,
"toolUsed": true
}
},
"twilio": {
"outgoing": {
"to": "<string>",
"from": "<string>",
"additionalParams": {}
}
},
"serverWebSocket": {
"inputSampleRate": 123,
"outputSampleRate": 123,
"clientBufferSizeMs": 123,
"dataMessages": {
"pong": true,
"state": true,
"transcript": true,
"clientToolInvocation": true,
"dataConnectionToolInvocation": true,
"playbackClearBuffer": true,
"callStarted": true,
"debug": true,
"callEvent": true,
"toolUsed": true
}
},
"telnyx": {
"outgoing": {
"to": "<string>",
"from": "<string>",
"additionalParams": {}
}
},
"plivo": {
"outgoing": {
"to": "<string>",
"from": "<string>",
"additionalParams": {}
}
},
"exotel": {},
"sip": {
"incoming": {},
"outgoing": {
"to": "<string>",
"from": "<string>",
"username": "<string>",
"password": "<string>"
}
}
},
"metadata": "<unknown>",
"templateContext": "<unknown>",
"experimentalSettings": "<unknown>"
}
],
"windowStart": "2023-11-07T05:31:56Z",
"windowEnd": "2023-11-07T05:31:56Z",
"webhookUrl": "<string>",
"webhookSecret": "<string>",
"paused": true
}
'{
"batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created": "2023-11-07T05:31:56Z",
"totalCount": 123,
"completedCount": 123,
"endedAt": "2023-11-07T05:31:56Z",
"windowStart": "2023-11-07T05:31:56Z",
"windowEnd": "2023-11-07T05:31:56Z",
"webhookUrl": "<string>",
"webhookSecret": "<string>",
"paused": true
}Authorizations
API key
Path Parameters
Body
1Show child attributes
Show child attributes
The call medium to use for the call. In particular, allows for specifying per-call recipients for outgoing media.
Show child attributes
Show child attributes
The call will use WebRTC with the Ultravox client SDK. This is the default.
Show child attributes
Show child attributes
Controls which data messages are enabled for the call.
Show child attributes
Show child attributes
Responds to a ping message. (Default: enabled)
Indicates that the agent state has changed. (Default: enabled)
Provides transcripts of the user and agent speech. (Default: enabled)
Requests a client-implemented tool invocation. (Default: enabled)
Requests a data-connection-implemented tool invocation. (Default: enabled for data connections, disabled otherwise)
Requests the client-side audio buffer to be cleared. (Default: enabled for websocket connections, disabled otherwise)
Provides information about the call when it starts. (Default: enabled)
Communicates debug information. (Default: disabled)
Indicates that a call event has been recorded. (Default: disabled)
Indicates that a tool was used. (Default: disabled)
The call will use Twilio's "Media Streams" protocol.
Once you have a join URL from starting a call, include it in your
TwiML like so:
Show child attributes
Show child attributes
If set, Ultravox will directly create a call with Twilio. Twilio must be configured for the requesting account.
Show child attributes
Show child attributes
The phone number, in E.164 format (e.g. +14155552671), (or sip address) to call.
The phone number or client identifier to use as the caller id. If to is a phone
number, from must be a phone number owned by your Twilio account.
Additional parameters to include in the Twilio call creation request. See https://www.twilio.com/docs/voice/api/call-resource#request-body-parameters
The call will use a plain websocket connection. This is unlikely to yield an acceptable user experience if used from a browser or mobile client, but may be suitable for a server-to-server connection. This option provides a simple way to connect your own server to an Ultravox inference instance.
Show child attributes
Show child attributes
The sample rate for input (user) audio. Required.
The desired sample rate for output (agent) audio. If unset, defaults to the input_sample_rate.
The size of the client-side audio buffer in milliseconds. Smaller buffers allow for faster interruptions but may cause audio underflow if network latency fluctuates too greatly. For the best of both worlds, set this to some large value (e.g. 30000) and implement support for playback_clear_buffer messages. Defaults to 60.
Controls which data messages are enabled for the call.
Show child attributes
Show child attributes
Responds to a ping message. (Default: enabled)
Indicates that the agent state has changed. (Default: enabled)
Provides transcripts of the user and agent speech. (Default: enabled)
Requests a client-implemented tool invocation. (Default: enabled)
Requests a data-connection-implemented tool invocation. (Default: enabled for data connections, disabled otherwise)
Requests the client-side audio buffer to be cleared. (Default: enabled for websocket connections, disabled otherwise)
Provides information about the call when it starts. (Default: enabled)
Communicates debug information. (Default: disabled)
Indicates that a call event has been recorded. (Default: disabled)
Indicates that a tool was used. (Default: disabled)
The call will use Telnyx's media streaming protocol.
Once you have a join URL from starting a call, include it in your
TexML like so:
Show child attributes
Show child attributes
If set, Ultravox will directly create a call with Telnyx. Telnyx must be configured for the requesting account.
Show child attributes
Show child attributes
The phone number to call in E.164 format (e.g. +14155552671).
The phone number initiating the call.
Additional parameters to include in the Telnyx call creation request. See https://developers.telnyx.com/api/call-scripting/initiate-texml-call
The call will use Plivo's AudioStreams protocol.
Once you have a join URL from starting a call, include it in your
Plivo XML like so:
Show child attributes
Show child attributes
If set, Ultravox will directly create a call with Plivo. Plivo must be configured for the requesting account.
Show child attributes
Show child attributes
The phone number(s) or sip URI(s) to call, separated by < if multiple.
The phone number initiating the call, in E.164 format (e.g. +14155552671).
Additional parameters to include in the Plivo call creation request. See https://www.plivo.com/docs/voice/api/call/make-a-call
The call will use Exotel's "Voicebot" protocol. Once you have a join URL from starting a call, provide it to Exotel as the wss target URL for your Voicebot (either directly or more likely dynamically from your own server).
The call will be connected using Session Initiation Protocol (SIP). Note that SIP incurs additional charges and must be enabled for your account.
Show child attributes
Show child attributes
Details for an incoming SIP call.
Details for an outgoing SIP call. Ultravox will initiate this call (and there will be no joinUrl).
Show child attributes
Show child attributes
The SIP URI to connect to. (Phone numbers are not allowed.)
The SIP URI to connect from. This is the "from" field in the SIP INVITE.
The SIP username to use for authentication.
The password for the specified username.
Optional metadata key-value pairs to associate with the call. All values must be strings.
The context used to render the agent's template.
The start of the time window during which calls can be made.
The end of the time window during which calls can be made.
The URL to which a request will be made (synchronously) when a call in the batch is created, excluding those with an outgoing medium. Required if any call has a non-outgoing medium and not allowed otherwise.
200The signing secret for requests made to the webhookUrl. This is used to verify that the request came from Ultravox. If unset, an appropriate secret will be chosen for you (but you'll still need to make your endpoint aware of it to verify requests).
120Response
The total number of calls in this batch.
The number of calls in this batch that have been completed (created or error).
The start of the time window during which calls can be made.
The end of the time window during which calls can be made.
The URL to which a request will be made (synchronously) when a call in the batch is created, excluding those with an outgoing medium. Required if any call has a non-outgoing medium and not allowed otherwise.
200The signing secret for requests made to the webhookUrl. This is used to verify that the request came from Ultravox. If unset, an appropriate secret will be chosen for you (but you'll still need to make your endpoint aware of it to verify requests).
120curl --request POST \
--url https://api.ultravox.ai/api/agents/{agent_id}/scheduled_batches \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"calls": [
{
"medium": {
"webRtc": {
"dataMessages": {
"pong": true,
"state": true,
"transcript": true,
"clientToolInvocation": true,
"dataConnectionToolInvocation": true,
"playbackClearBuffer": true,
"callStarted": true,
"debug": true,
"callEvent": true,
"toolUsed": true
}
},
"twilio": {
"outgoing": {
"to": "<string>",
"from": "<string>",
"additionalParams": {}
}
},
"serverWebSocket": {
"inputSampleRate": 123,
"outputSampleRate": 123,
"clientBufferSizeMs": 123,
"dataMessages": {
"pong": true,
"state": true,
"transcript": true,
"clientToolInvocation": true,
"dataConnectionToolInvocation": true,
"playbackClearBuffer": true,
"callStarted": true,
"debug": true,
"callEvent": true,
"toolUsed": true
}
},
"telnyx": {
"outgoing": {
"to": "<string>",
"from": "<string>",
"additionalParams": {}
}
},
"plivo": {
"outgoing": {
"to": "<string>",
"from": "<string>",
"additionalParams": {}
}
},
"exotel": {},
"sip": {
"incoming": {},
"outgoing": {
"to": "<string>",
"from": "<string>",
"username": "<string>",
"password": "<string>"
}
}
},
"metadata": "<unknown>",
"templateContext": "<unknown>",
"experimentalSettings": "<unknown>"
}
],
"windowStart": "2023-11-07T05:31:56Z",
"windowEnd": "2023-11-07T05:31:56Z",
"webhookUrl": "<string>",
"webhookSecret": "<string>",
"paused": true
}
'{
"batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created": "2023-11-07T05:31:56Z",
"totalCount": 123,
"completedCount": 123,
"endedAt": "2023-11-07T05:31:56Z",
"windowStart": "2023-11-07T05:31:56Z",
"windowEnd": "2023-11-07T05:31:56Z",
"webhookUrl": "<string>",
"webhookSecret": "<string>",
"paused": true
}