Asterisk course

Asterisk Dial Application: Destinations, Timeouts, Options, and URLs

Learn how Asterisk Dial calls one or more endpoints, bridges answered channels, and uses destinations, timeouts, options, and URLs in a dialplan.

The Dial application places a call attempt from the current dialplan channel to one or more destinations. When a destination answers, Asterisk creates a bridge: a connection that joins the original caller and the answering channel so they can communicate.

Dial can connect different channel technologies. For example, an inbound caller can be connected to a SIP-based phone, an IAX2 device, or an analog-connected endpoint if the appropriate channel technology and endpoint are configured.

This lesson assumes familiarity with Asterisk dialplans, extensions, channels, endpoints, and priorities.

Dial Application Syntax

The general argument order is:

Dial(destination[,timeout[,options[,URL]]])

The arguments are positional. This means Asterisk interprets the first value as the destination, the second as the timeout, the third as the options string, and the fourth as the URL. You cannot place an option in the third position without preserving the second position, even when you do not want to set a timeout.

Calling One Destination

A destination uses the Technology/Resource format. The technology identifies the channel driver or endpoint type. The resource identifies the particular peer, device, or endpoint that should be called.

For example:

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

Here, SIP identifies the channel technology and 100 identifies the configured SIP peer or endpoint. The resource must match an endpoint that Asterisk knows about and can reach. A typo, an unregistered device, or an incorrect technology prefix can prevent the call from being placed.

Dial starts the outbound call attempt from the current channel. If SIP/100 answers, Asterisk bridges that channel to the original caller.

Dialing Multiple Destinations at the Same Time

Place multiple destinations in the destination argument and separate them with an ampersand (&):

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

Both targets are called concurrently. In this example, Asterisk attempts to call the SIP endpoint named alice and the IAX2 endpoint named 200. These endpoints can use different channel technologies.

The first destination to answer wins. Asterisk bridges that answering destination to the caller and stops the remaining call attempts from ringing. The other endpoints are not connected to the conversation.

Controlling Ringing with a Timeout

The timeout argument is measured in seconds. It specifies how long Dial should continue the call attempt before returning to the dialplan without an answer.

When no timeout is provided, dialing can continue until a destination answers or the caller hangs up. This behavior can prevent a following fallback priority from being reached during a normal unanswered call.

With a timeout, Dial stops trying after the specified interval. Dialplan execution can then continue at the next priority:

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

This example rings both destinations for up to 20 seconds. If neither answers, execution continues to the next priority, plays an unavailable message, and terminates the call. Playback provides the announcement, while Hangup ends the call.

Using Dial Options

The third argument is an option string. Option letters change how Dial behaves and must appear after the timeout argument.

The m Option

The m option provides music on hold to the caller instead of ordinary ringing while Asterisk calls the destination:

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

The caller hears configured music on hold during the 20-second call attempt. The called endpoints still receive the call attempt. If one answers, the bridge is created as usual.

If no timeout is intended, preserve the empty second argument:

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

The two consecutive commas represent an empty timeout field. Without them, m would be interpreted in the timeout position rather than as an option.

Using the URL Argument

The fourth argument is an optional URL associated with the called destination. A URL can provide information related to the call, such as a page an endpoint could display.

URL delivery is dependent on both the destination channel and the endpoint. A capable IP phone might present the URL on its display, while another phone or channel technology might ignore it. URL support should therefore be treated as optional rather than assumed.

Because the URL is the fourth argument, the earlier positions must be preserved. For example, a URL used with a timeout but no options would follow the timeout field and an empty options field:

Dial(SIP/100,20,,https://example.invalid/info)

The example shows argument placement only. Use a URL appropriate for your environment and verify that the target device supports receiving and displaying it.

Understanding What Happens When Dial Returns

Dial normally occupies the current priority while it attempts to call the destination. If a destination answers, the caller and answering channel are bridged. When the call attempt ends without an answer, or when the timeout expires, Dial returns control to the dialplan.

Sequential priorities can define the fallback behavior:

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

1. Priority 1 starts simultaneous calls to the two destinations.
2. After 20 seconds without an answer, Dial returns.
3. The next priority plays the unavailable announcement.
4. The final priority hangs up the channel.

This is ordinary dialplan control flow: the timeout determines when Dial gives control back, and the following priorities determine what happens next.

Complete Examples

One SIP Peer

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

This calls one configured SIP endpoint. With no timeout, the call attempt continues until the endpoint answers or the caller disconnects.

Parallel SIP and IAX2 Ringing

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

The SIP and IAX2 destinations ring at the same time. The first answer is bridged to the caller.

Parallel Ringing with Timeout and Fallback

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

This limits the attempt to 20 seconds and provides a clear no-answer path.

Music on Hold During the Attempt

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

The caller hears music on hold rather than ordinary ringing while the endpoints are being called.

Troubleshooting Dial

• Options do not work: The option may have been placed in the timeout position. Use Dial(destination,,m) when no timeout is intended.
• The fallback announcement never plays: No timeout may have been supplied. Add a timeout so Dial can return to the next priority when nobody answers.
• Only one endpoint rings: The destinations may not be separated with &. Use one destination argument such as SIP/alice&IAX2/200.
• A URL does not appear: The channel or phone may not support receiving or displaying Dial URL data. Verify endpoint capabilities and treat display as optional.
• The expected endpoint is not called: Check that the Technology/Resource value matches a configured and reachable endpoint. Confirm both the technology prefix and resource name.

Exam-Relevant Notes

• Dial originates call attempts from the current dialplan channel and bridges an answering destination to the caller.
• The argument order is destination, timeout, options, URL.
• Destinations use Technology/Resource, such as SIP/100.
• Use & for simultaneous dialing; the first destination to answer is connected.
• Timeout values are in seconds. Without a timeout, Dial may continue until answer or caller hangup.
• Use consecutive commas to preserve an empty optional argument, such as Dial(destination,,m).
• After a timed-out Dial returns, the next dialplan priority can play an announcement or execute another fallback action.
• URL delivery depends on support from the destination channel and endpoint.