Skip to main content
POST

Create Dispatch

Trigger an outbound call or an in-browser WebRTC session with a single endpoint. Use the medium parameter to choose the delivery channel:

Important Concepts

Agent ID

You must pass an agent_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

The metadata object contains template variables that you configure while creating the agent.
  • Each key in metadata corresponds 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)

The modify_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
Important Rules:
  1. 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)
  2. 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_agent values taking priority.
  3. 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 page
  • medium: "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 to true to 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 connect
  • welcome_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)

Use persona.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 success
object
Call dispatch details
string | null
Error message if the operation failed, null on success

WebRTC 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

The live_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