Calls
Create Dispatch
Trigger an outbound telephony call or an in-browser WebRTC session
POST
Create Dispatch
Trigger an outbound call or an in-browser WebRTC session with a single endpoint. Use themedium parameter to choose the delivery channel:
Important Concepts
Agent ID
You must pass anagent_id, which is a UUID that uniquely identifies an agent.
You can obtain the agent_id from the Agent Config page on the Vaani portal:
- Go to app.vaanivoice.ai
- Navigate to Agent Config
- Select your agent
- Copy the Agent ID (UUID)
Metadata
Themetadata object contains template variables that you configure while creating the agent.
- Each key in
metadatacorresponds to a variable used in the agent’s prompt or flow - These values are dynamically injected at call time
- The structure depends on how the agent was configured
Modify Agent (Runtime Config Override)
Themodify_agent parameter allows you to override parts of the agent configuration at call time. This works for both telephony and webrtc mediums. It is useful for:
- Customizing agent behavior per call without creating multiple agents
- Dynamically adjusting settings based on the contact or campaign
- Testing configuration changes before making them permanent
-
Only the following top-level sections are accepted:
persona- Agent persona (identity, senses_capabilities, actions, memories)training- Agent training (knowledge, know_how, guardrails)experience- Agent experience (conversational_experience, settings)analysis- Agent analysis (evaluations, extraction)
-
You must provide the complete JSON structure for any section you want to modify. The provided configuration will be deep-merged with the agent’s base config, with
modify_agentvalues taking priority. - For nested objects, only the keys you provide will be overridden - other keys in the base config will be preserved.
Required Fields
agent_id: Agent UUID from the Agent Config pagemedium:"telephony"(default) or"webrtc"
Required for medium="telephony" only
contact_number: Contact number with country code (e.g., +919876543210)name: Customer name
Optional Telephony Fields
outbound_number: Specific outbound caller ID to use (E.164 format)dnd_check_skipped: Set totrueto skip the Do Not Disturb (DND) check
Optional WebRTC Fields (ignored for medium="telephony")
voice_gender:"male"|"female"(default:"female")primary_language: Primary language code, e.g."en","hi"(default:"hi")secondary_language: Fallback language code (default:"en")welcome_message: Custom greeting the agent speaks on connectwelcome_interruptible: Whether the welcome message can be interrupted (default:true)bg_noise_enabled: Enable background noise (default:false)bg_noise_volume: Background noise volume 0–100 (default:60)voice_speed: Speech speed multiplier 0.6–1.4 (default:1.0)
Runtime Config Override
modify_agent: Agent config sections to override at call time (supported for both mediums)
Parameters
string
Optional. A custom identifier forwarded to your BYOL WebSocket server in the
x_agent_id field of every turn request’s req_body. (THIS IS NOT SAME AS
agent_id WHICH YOU PASS IN THE req.body IT IS YOUR CUSTOM ID WHICH YOU WANT
TO USE) Useful for routing or auditing across multiple agents sharing the same
WebSocket server.string
required
Agent UUID obtained from the Agent Config page on the portal
string
default:"telephony"
Call delivery medium:
"telephony" for an outbound SIP/PSTN call, or
"webrtc" for an in-browser WebRTC session.object
default:"{}"
Template variables configured while creating the agent
object
default:"null"
Runtime configuration override. Accepted for both mediums. Accepts only these top-level keys:
persona, training, experience, analysis. Each key must contain the complete JSON structure for that section. Values are deep-merged with the base agent config.When BYOL (Bring Your Own LLM) is enabled for the agent, the full modify_agent object — including persona.metadata template variables — is forwarded to your WebSocket server in the req_body field of every turn request. See BYOL request payload and the modify_agent examples below.Telephony Parameters
string
Contact number with country code (e.g., +919876543210). Required when
medium="telephony".string
Customer name. Required when
medium="telephony".string
default:""
Voice preference (optional, telephony only)
boolean
default:"false"
Set to
true to skip the Do Not Disturb (DND) check for this call. Telephony
only.string
default:"null"
Optional outbound caller ID to use (E.164 format). Telephony only.
WebRTC Parameters
string
default:"female"
Voice gender preset:
"male" | "female". WebRTC only.string
default:"hi"
Primary language code for the session (e.g.
"en", "hi"). WebRTC only.string
default:"en"
Fallback language code for the session. WebRTC only.
string
Custom greeting the agent speaks when the call connects. Overrides the agent’s
default greeting. WebRTC only.
boolean
default:"true"
Whether the welcome message can be interrupted by the user speaking. WebRTC
only.
boolean
default:"false"
Enable background noise for the session. WebRTC only.
integer
default:"60"
Background noise volume (0–100). WebRTC only.
number
default:"1.0"
Speech speed multiplier (0.6–1.4). WebRTC only.
Request Body
Request Example
modify_agent Examples
Example 1: Football Expert Agent (Telephony)
Example 2: Medical Appointment Reminder (Telephony)
Example 3: Custom WebRTC Session with Override
Example 4: Survey with Custom Data Collection (Telephony)
Example 5: BYOL with Per-Call Template Variables (Telephony)
Usepersona.metadata to pass per-call variables that get injected into {{placeholder}} references in the system prompt. These values are forwarded to your BYOL WebSocket server in req_body.modify_agent.persona.metadata.
Response
Telephony Success Response (200)
Telephony Response Fields
boolean
Whether the call was dispatched successfully
string
Status message —
"Call initiated successfully" on successobject
Call dispatch details
string | null
Error message if the operation failed,
null on successWebRTC Response Fields
string
Short-lived JWT for WebRTC authentication. Pass this to the WebRTC client SDK
to connect.
string
The LiveKit room the agent has been dispatched to.
string
Agent identifier that was dispatched.
string
WebRTC server WebSocket URL (
wss://...). Use this as the server URL in the
WebRTC client SDK.string
WebSocket URL for real-time live captions/transcripts streaming.
Live Captions
Thelive_captions_url in the response provides a WebSocket endpoint for streaming real-time transcripts during the call. It works identically for both telephony and WebRTC sessions.
Message Types
Transcript Segment Structure
Validation Error (422)
array
Array of validation error objects

