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:User Element
Dial a SIP endpoint:
Attribute names are camelCase (
sipAuthUsername, not sip_auth_username).
Authenticated SIP call example:
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:confirmSound URL should return XML like:
Custom Caller ID
Custom Ringback
Play custom audio instead of the standard ring:dialMusic="real" to play the actual ringtone from the carrier.
Dial Extensions
Send DTMF tones after the call connects (useful for extensions):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 theaction URL:
Dial Callback URL Parameters
Real-time events sent tocallbackUrl:
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:Conditional IVR Flow
Menu Loop
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
- Avoid infinite loops - Ensure redirects eventually lead to an endpoint that doesn’t redirect
- Handle errors - Your redirect URL should always return valid XML
- Use HTTPS - All URLs should use HTTPS
- 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: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, andWaitelements are allowed - Call is not “answered” during PreAnswer, so some carriers may timeout
- Recommended to keep PreAnswer duration under 30 seconds
Related
- Audio Output - Speak, Play, DTMF
- Input Collection - GetDigits, GetInput
- Conference - Conference calls
- Multi-party Call - Role-based multi-party calls
- Audio Streaming - Stream real-time audio