Dial

The Dial verb connects the current call to another party (phone number, SIP endpoint, or TryVox client).

Example

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Dial",
      "numbers": [
        {"number": "+919876543210"}
      ],
      "timeout": 30,
      "caller_id": "+911234567890"
    }
  ]
}

Parameters

Parameter	Type	Required	Default	Description
action_url	string	no	—	URL to POST dial status to
timeout	integer	no	30	Seconds to wait for answer
time_limit	integer	no	14400	Maximum call duration in seconds (4 hours)
caller_id	string	no	—	Caller ID to display
record	boolean	no	false	Record the call
ring_tone	string	no	—	Country code for ring tone (e.g., "IN", "US")
numbers	array	no	—	Array of phone numbers to dial
sip	array	no	—	Array of SIP endpoints to dial
client	array	no	—	Array of TryVox client names to dial

Dialing Phone Numbers

Dial a single number:

{
  "verb": "Dial",
  "numbers": [
    {"number": "+919876543210"}
  ]
}

Dial multiple numbers simultaneously (first to answer wins):

{
  "verb": "Dial",
  "numbers": [
    {"number": "+919876543210"},
    {"number": "+919123456789"}
  ]
}

Send DTMF digits after connection:

{
  "verb": "Dial",
  "numbers": [
    {
      "number": "+919876543210",
      "send_digits": "1234#"
    }
  ]
}

Dialing SIP Endpoints

{
  "verb": "Dial",
  "sip": [
    {
      "uri": "sip:agent@sip.example.com",
      "username": "user123",
      "password": "pass456"
    }
  ]
}

Dialing TryVox Clients

{
  "verb": "Dial",
  "client": [
    {"name": "support-agent-1"},
    {"name": "support-agent-2"}
  ]
}

Recording Calls

Enable call recording:

{
  "verb": "Dial",
  "numbers": [{"number": "+919876543210"}],
  "record": true
}

Time Limits

Set a timeout for ringing (seconds to wait for answer):

{
  "verb": "Dial",
  "numbers": [{"number": "+919876543210"}],
  "timeout": 20
}

Set a maximum call duration:

{
  "verb": "Dial",
  "numbers": [{"number": "+919876543210"}],
  "time_limit": 3600
}

Caller ID

Override the caller ID displayed to the dialed party:

{
  "verb": "Dial",
  "numbers": [{"number": "+919876543210"}],
  "caller_id": "+911234567890"
}

Callback

If you provide an action_url, TryVox will POST the dial status when the call ends:

{
  "verb": "Dial",
  "numbers": [{"number": "+919876543210"}],
  "action_url": "https://example.com/dial-status"
}

The callback payload includes:

{
  "call_uuid": "abc-123",
  "dial_status": "completed",
  "dial_duration": 120,
  "recording_url": "https://recordings.tryvox.ai/rec_xyz.mp3"
}

Possible dial_status values:

completed - Call was answered and completed normally
busy - Dialed party was busy
no-answer - Call was not answered within timeout
failed - Call failed to connect
canceled - Call was canceled

Best Practices

Set appropriate timeout values (20-30 seconds typical)
Use time_limit to prevent unexpectedly long calls
When dialing multiple numbers, order them by priority
Use send_digits for navigating IVR systems

Dial

On this page