VMware ESXi and vSphere Cluster Management

Asterisk Dial Application: Destinations, Timeouts, and Options

Learn how Asterisk Dial calls SIP, IAX2, and other destinations, controls ringing time, uses options and URLs, and continues dialplan execution.

The Asterisk Dial application places one or more outbound call attempts from the current dialplan channel. When a destination answers, Asterisk normally bridges the original caller to that answering destination. After the call ends or dialing does not produce an answer, control can return to later priorities in the dialplan.

A channel is an Asterisk call leg representing a caller, endpoint, trunk, or other call resource. The dialplan is the call-routing logic made up of contexts, extensions, priorities, and applications. Dial creates additional channel legs for the destinations that you specify.

Destinations can use different channel technologies. Common examples include SIP, a signaling technology used by many IP phones and softphones, and IAX2, an Asterisk-oriented signaling and media protocol. Analog channels and other supported technologies can also be used.

Dial application syntax

Dial has four comma-separated argument positions:

Dial(destination,timeout,options,URL)

Arguments must remain in this order. Because later arguments depend on earlier positions, omitted arguments require empty placeholders. For example, options without a timeout use two commas after the destination:

Dial(SIP/alice&IAX2/200,,m)

Destination: Technology/Resource

The first Dial argument is the destination. A destination normally uses the Technology/Resource format:

Technology/Resource

Technology identifies the channel driver or endpoint type. Resource identifies the peer, device, number, or other target within that technology. A peer is a configured endpoint or remote entity that can be addressed through a channel technology.

Calling one SIP endpoint

This example calls the configured SIP peer or endpoint named 100:

exten => 100,1,Dial(SIP/100)

The current channel attempts to call SIP/100. If the endpoint answers, Asterisk bridges the caller and that endpoint.

Calling one IAX2 endpoint

Dial(IAX2/200)

Here, IAX2 is the technology and 200 is the resource. The referenced IAX2 endpoint must be configured and registered or otherwise reachable.

Simultaneous dialing

Separate multiple destinations with an ampersand (&) inside the single destination argument:

exten => 200,1,Dial(SIP/alice&IAX2/200)

With simultaneous dialing, the first destination to answer normally wins. Asterisk bridges that destination to the original caller and stops the remaining destinations from ringing.

Timeout behavior

The second Dial argument is a timeout measured in seconds. This limits how long Dial continues attempting the destination:

Dial(SIP/alice,20)

When no timeout is supplied, dialing continues until a destination answers or the caller hangs up. That behavior means later no-answer priorities may not run after a fixed period.

When a configured timeout expires without an answer, Dial returns control to the next priority in the extension. A basic no-answer flow can play an announcement and then hang up:

exten => 200,1,Dial(SIP/alice&IAX2/200,20)
same => n,Playback(vm-nobodyavail)
same => n,Hangup()

In this example, Asterisk rings both destinations for up to 20 seconds. If neither answers, priority 2 runs Playback(), and the following priority runs Hangup().

Options and music on hold

The third Dial argument is an option string: one or more flags that change Dial behavior. The m option provides music on hold to the caller while the destination rings. Music on hold is audio supplied to a waiting caller instead of normal ringing indications.

Use the option after a timeout like this:

exten => 200,1,Dial(SIP/alice&IAX2/200,20,m)

If you want music on hold but do not want to set a timeout, leave the timeout field empty:

exten => 200,1,Dial(SIP/alice&IAX2/200,,m)

URL argument

The fourth Dial argument is an optional URL. Asterisk delivers it to the called endpoint only when the channel technology and the destination device support URL delivery. A compatible IP telephone might display the URL or make it available for the user to open.

exten => 300,1,Dial(SIP/100,20,,https://pbx.example.invalid/call-info)

The empty third argument is required because the URL is position four. URL support is device- and channel-dependent, so do not make essential call routing depend on the URL appearing on the phone.

Dialplan flow after Dial returns

Dial is an application executed at a particular priority, which is an ordered execution step within an extension. If Dial returns without leaving the call bridged, subsequent priorities can provide no-answer or failure handling.

exten => 410,1,Dial(SIP/410,20)
same => n,Playback(vm-nobodyavail)
same => n,Hangup()

The exact reason Dial returns can vary. A call may be answered, reach its timeout, fail because a destination is unavailable, or be interrupted because the caller disconnects. Production call-routing logic should account for those outcomes rather than assuming every return means the same thing.

For more precise decisions, use Dial result and status handling, including the DIALSTATUS channel variable, together with conditional routing such as GotoIf(). That is an advanced follow-up topic; the basic pattern remains that Dial attempts the call and later priorities handle what happens when the attempt returns.

Endpoint prerequisites

• Define the referenced SIP peer or endpoint before dialing it.
• Define and register, or otherwise make reachable, each referenced IAX2 or other technology resource.
• Verify that the resource name in the Technology/Resource expression matches the configured endpoint.
• Configure music on hold before using the m option.
• Confirm URL support on the called device and channel driver before using the URL argument.

Troubleshooting Dial applications

An option is interpreted incorrectly

Likely cause: The timeout position was omitted instead of left blank.

Resolution: Use an empty timeout field before the option string:

Dial(SIP/alice&IAX2/200,,m)

Only one endpoint rings

Likely causes: The destinations were not combined with &, or one destination is unavailable.

Resolution: Put all targets in one destination argument, separated by &, and verify the configuration and reachability of each endpoint.

The no-answer announcement does not play

Likely cause: No timeout was specified, so Dial continues until an answer or caller disconnect.

Resolution: Supply a timeout and put Playback() and Hangup() at the following priorities.

The caller hears ringing instead of music on hold

Likely causes: The m option is absent, incorrectly positioned, or music on hold is not configured.

Resolution: Place m in the third argument and verify the music-on-hold configuration.

The call rings beyond the intended duration

Likely cause: The timeout is missing, malformed, or not in the second Dial argument.

Resolution: Specify a numeric timeout in seconds immediately after the destination:

Dial(SIP/alice,20)

The URL does not appear on the called phone

Likely cause: The destination channel or endpoint does not support URL delivery.

Resolution: Verify device capability and channel-driver support. Treat URL display as an optional feature.

Key points

• Dial originates outbound call attempts from the current channel and bridges a successful answer to the caller.
• Destinations use Technology/Resource notation, such as SIP/100 or IAX2/200.
• Use & to dial multiple destinations simultaneously; the first answer normally wins.
• The timeout is the second argument and is expressed in seconds.
• Use later dialplan priorities for announcements, hangup, or more advanced status-based routing.
• The m option provides music on hold while destinations ring.
• Empty comma-separated fields preserve argument positions when an earlier optional argument is omitted.
• URL delivery works only when both the channel technology and endpoint support it.

For the complete lesson on this topic, see The Dial Application.