Skip to main content
This page covers the XML elements for call routing: connecting to other parties, transferring call flow, ending calls, and pausing execution.

Dial

The <Dial> element connects the current call to another phone number, SIP endpoint, or Plivo user. When the dialed party answers, both parties are connected. When either party hangs up, the connection ends.

Basic Usage

Dial Attributes

Callback Attributes

Nested Elements

<Dial> must contain at least one nested element:

Number Element

Dial a phone number:
Number Attributes:

User Element

Dial a SIP endpoint:
User Attributes: Attribute names are camelCase (sipAuthUsername, not sip_auth_username). Authenticated SIP call example:
Hangup causes on auth failure: If outbound SIP authentication fails, the Dial action URL receives these values: Reserved sipHeaders prefixes: Customer sipHeaders keys with the following prefixes (case-insensitive) are silently dropped: PH-, Plivo, FS-, SipAuth, ZT-, Twilio. The exact name ClientRegion is also reserved. See SIP Authentication for details. Raw-mode rendering with SIP authentication: When the inbound leg used SIP authentication, sipHeaders are emitted on the outbound B-leg INVITE without the X-PH- prefix (e.g., CustomerId=123 renders as X-CustomerId: 123 rather than X-PH-CustomerId: 123).

Simultaneous Dialing

Ring multiple numbers at once. First to answer is connected:

Sequential Dialing

Try numbers one at a time with timeouts:

Dial with Confirmation

Require the called party to press a key to accept:
The confirmSound URL should return XML like:

Custom Caller ID

Custom Ringback

Play custom audio instead of the standard ring:
Use dialMusic="real" to play the actual ringtone from the carrier.

Dial Extensions

Send DTMF tones after the call connects (useful for extensions):
Each w adds a 0.5-second pause. This example waits 2 seconds, then dials extension 1234.

Dial Action URL Parameters

When the dial completes, these parameters are sent to the action URL:

Dial Callback URL Parameters

Real-time events sent to callbackUrl:

Dial to SIP


Redirect

The <Redirect> element transfers call execution to a different URL. Plivo fetches new XML instructions from the specified URL and continues the call.

Basic Usage

Redirect Attributes

Dynamic Routing

Redirect based on conditions:

After Dial Failure

Redirect when a dial attempt fails:
If the dial fails or times out, the call redirects to voicemail.

Conditional IVR Flow

Create a menu that returns to itself:

Redirect with GET Method

Redirect Request Parameters

When Plivo calls the redirect URL, it includes all standard request parameters:

Redirect Best Practices

  1. Avoid infinite loops - Ensure redirects eventually lead to an endpoint that doesn’t redirect
  2. Handle errors - Your redirect URL should always return valid XML
  3. Use HTTPS - All URLs should use HTTPS
  4. Pass context - Use query parameters to pass state between endpoints

Hangup

The <Hangup> element terminates the current call. Use it to gracefully end calls after completing a flow.

Basic Usage

Hangup Attributes

Scheduled Hangup

End the call after a delay:
This schedules a hangup while continuing to execute subsequent elements.

Reject with Reason

Provide a hangup reason to simulate different call states:

After IVR Timeout

After Business Hours

Block Spam Callers

Implicit Hangup

If your XML doesn’t end with <Hangup>, the call automatically ends when all elements are executed. However, it’s good practice to include it explicitly for clarity.

Wait

The <Wait> element pauses call execution for a specified duration. Use it for hold times, delays, or with answering machine detection.

Basic Usage

Wait Attributes

Silent Wait

By default, <Wait> plays hold music. For silence:

Delayed Call Answer

Use <Wait> to delay answering (useful for screening):

Answering Machine Detection

Detect answering machines by listening for beeps:

Beep Detection Parameters

For fine-grained control, pass beep parameters as a comma-separated string:

Silence Detection

Detect when the other party stops speaking:
minSilence is the minimum silence duration in milliseconds to trigger detection.

Machine Detection Flow

Combine with <Speak> for voicemail drops:

Use in PreAnswer

Delay before answering the call:

PreAnswer

The <PreAnswer> element plays audio to the caller before the call is answered. This is useful for custom ringback tones or screening calls. The caller is not billed during this phase.

Basic Usage

Nested Elements

<PreAnswer> can contain:
  • <Speak> - Text-to-speech messages
  • <Play> - Audio files
  • <Wait> - Pauses

Custom Ringback

Play music while connecting:

Use Cases

Limitations

  • Only Speak, Play, and Wait elements are allowed
  • Call is not “answered” during PreAnswer, so some carriers may timeout
  • Recommended to keep PreAnswer duration under 30 seconds