Section 17.3. Asterisk Dial-Plan

17.3. Asterisk Dial-Plan

All calls placed to, from, and through the Asterisk PBX are handled on logical voice pathways. A pathway may consist of a single hard line, like an analog telephone line interfaced with Asterisk via an X100P card, or there may be hundreds of pathways sharing a single physical connection, like a bunch of SIP phones connected to the Asterisk server via an Ethernet interface. In any scenario, the pathways are called channels , and the Asterisk PBX's purpose is to handle their voice traffic according to a set of rules known as a dial-plan . The effect the dial-plan has on a call is called a call flow .

Many conventional PBX systems use dial-plans to deal only with calls that can be placed and answered when a human is present and require an offboard voice mail server with an auto-attendant to answer calls when nobody's in the office. But the Asterisk PBX uses dial-plan for a much larger purpose: complete call processing for both scenarios. The Asterisk dial-plan includes rules that specify what to do when:

A call comes in on a particular channel or from a certain calleri.e., if the call is from this line, handle it a certain way
A call comes in at a certain time of day or on a certain day of the weeki.e., if the call comes in after hours, play an out-of-office message
A certain callee does not answer in a timely manneri.e., if Bob doesn't answer within 25 seconds, try Sue instead
A caller dials certain keys in response to recorded promptsi.e., the caller is prompted to press 1 for sales, 2 for support, and so on, and the proper action is taken
A caller is placed on hold or needs to enter a hold queuei.e., during hold, the user may hear music or a commercial; she may be on hold indefinitely or for a limited time before something else happens
A caller performs a multiparty conference or transfers a telephone call to another extensioni.e., several people are participating in a single call, and the dial-plan describes the parameters for that call
A subscriber wants to manage his voice mailboxi.e., Bob presses his voice mail button on his IP phone because his message-waiting indicator is lit
...and lots of other scenarios

The dial-plan is the command center of the Asterisk system. Almost every dial-plan function you can access requires a visit to the dial-plan's main configuration file: extensions.conf . This file defines all of the possible call destinations (extensions), which may include users' telephones, hold queues, voice mailboxes, or call processors.

extensions.conf describes call-routing scenarios, called extensions . Other configuration files, like SIP.conf and zaptel.conf , describe endpoint channels and trunk channelsthe actual originators and receivers of calls.

In Asterisk, extensions aren't defined as physical PBX telephones in the traditional sense, but as what-to-do scenarios that are referenced by numbers. Put another way, each extension answers the question, "What should the PBX do when this extension number is invoked?" The answer isn't always to ring a phonenot all extension numbers are actually related to phones as they tend to be on a traditional PBX. Indeed, on Asterisk, some extensions may be related to voice mailboxes or custom call processors. Extension number 501 might ring a phone, but extension number 105 might play a voice mail announcement and then record the caller's message.

The numbersphone numbersprovide legacy compatibility so that Asterisk extensions can be used with the old 12-key dial-pad on legacy phones. This conforms to the conventions of the ITU's numbering standard, E.164. But, as VoIP becomes more prevalent , you'll discover that Asterisk can be used with alphanumeric addresses, which are common with SIP.

When the extension asks "What should the PBX do when this extension is invoked," the answer comes in the form of an Asterisk application commanda task-specific call-handling function. There are many application commands for different tasks , and each answers that question with its own functionality. Here's a (very) partial list:

Dial: The Dial command is one of the most commonly used in Asterisk. Its only purpose is to open a second channel, place a call, and connect that call with the caller on the current channel.
Voicemail: This command plays back a voice mail greeting and optionally attempts to record a message on behalf of the caller on the current channel.
Background: The user hears a sound file, and the digits she dials are captured and handled.
Monitor: This command records the conversation on the current channel and saves it into a file.
Zapateller: This command plays a special tone designed to block telemarketers on the current channel, much like the popular TeleZapper device marketed by Royal Appliance Manufacturing Co.
System: A command line is relayed to the Linux shell for immediate execution.

17.3.1. Variables

Asterisk's extensions.conf and voicemail.conf files can use variables in a manner similar to shell scripts. Variables can be contained within a particular voice channel or be made "global," available to all contexts of the dial-plan. (More on contexts later.) Variables are referenced using curly brackets ( { and } ) around the variable name , preceded by a dollar sign ( $ ). Here's an example of a variable called announceBox being assigned, then recalled:

 exten => 1,1,SetGlobalVar(announceBox=15)     exten => 1,2,NoOp(${announceBox})

17.3.1.1 Built-in variables

Asterisk has a number of built-in variables to handle specific tasks. They behave like functions: ${DATETIME} provides a reference to the current system time, while ${ CALLERID } provides caller ID information. Built-in variables are almost always channel-specificthat is, they don't have much meaning outside the scope of a particular call.

The PBX can behave differently depending on the time of day, the caller's identification, and even the channel used to handle a call. The more you use configuration settings, commands, and variables with Asterisk's configuration files, the more the syntax of the configuration files will make sense. For now, let's talk about the place where commands and variables are most often employed: the dial-plan.

17.3.1.2 The layout of extensions.conf

There are three section categories in the extensions.conf file, each headed by a square-bracketed ( [ and ] ) string that contains each section's name. The first section category, called [general] , allows you to change two settings static and writeprotect . Neither of these settings has much consequence in learning Asterisk, so you can ignore both of them or even leave them out of the file altogether for now.

The second section category, called [ globals ] , is for defining global variables, which are administrator-assignable values that can be recalled throughout the dial-plan. A good example would be assigning a vague channel name ( Zap/1 ) to a meaningful variable ( TELEPHONECOMP ), like this:

 [globals]     TELEPHONECOMP => Zap/1

You could also use the globals section to store a list of hard-to-remember channel names for a group of SIP or analog phones:

 [globals]     CAFEPHONE => SIP/105@oreilly.com:5060     OFFICEPHONE => SIP/106@oreilly.com:5060     CORDLESSPHONE => Zap/2

Notice how the structure of a channel name variesa Zaptel legacy channel has a very simple name structure ( Zap/2 ), but a SIP channel has a complex name structure ( SIP/106@oreilly.com:5060 ). SIP has a URI naming, while legacy channels have no such convenience. Asterisk therefore names legacy POTS and PRI channels by referencing their hardware interfaces ( Zap/1 , Zap/2 , and so forth).

A channel called SIP/106@oreilly.com:5060 is the same as a channel called SIP/106 , as long as 106 is defined as a peer in sip.conf and oreilly.com is the default SIP domain name. See "SIP Channels," later in this chapter, for more details..

The variables assigned in the globals section don't actually cause Asterisk to do anything. They merely store information that can be used elsewhere in the dial-plan.

17.3.1.3 Contexts

The third section of extensions.conf consists of multiple sections known as contexts. While there can only be one general and one globals section in extensions.conf , there can be many context sections. In fact, there can be as many contexts as you like. But, just what is a context?

With a cutomizable softPBX like Asterisk, you have the ability to set up limitless dial-plan scenarios. So, you may still have day and night modes, but you may also have lunchtime mode, happy hour mode, etc., depending on your users' needs. Asterisk refers to these modes of operation contexts . Contexts organize related extension numbers in the dial-plan so that they create call flows that are explicitly defined for any combination of:

What channel the call is coming in on
What time of day it is
What type of endpoint originated the call
Specifically, which endpoint originated the calli.e., was it Bob's phone or Sue's?
What extensions should be reachable by the current caller

For example, an initial catchall greeting might say, "Press 1 for Marketing, 2 for Sales, and 3 for Service." Let's say the user presses 1. He may then hear another greeting that says, "Press 1 for the Head of Marketing, 2 for the Secretary of Marketing, or 3 for the Ad Buyer."

So, in one context, option 1 is for the Marketing Department, but in a subsequent context, option 1 is for the head of marketing. Contexts give you, the administrator, programmatic control over call flows, but they also give you access control abilities at the application layer.

Here's the configuration of three contexts to re-create the call flow described in Figure 17-1:

 [default]    ; (main context)     exten => s,Playback(main-greeting)     exten => s,2,WaitExten( )     exten => 1,1,Goto(Sales,1)     exten => 2,1,Goto(Marketing,1)     [Sales]     exten => s,1,Playback(sales-dept-greeting)     exten => s,2,WaitExten( )     exten => 1,1,Goto(NewCustomers,1)     exten => 2,1,Goto(ReturningCustomers,1)     [Marketing]     exten => s,1,Playback(marketing-dept-greeting)     exten => s,2,WaitExten( )     exten => 1,Dial(${headOfMarketing})     exten => 2,Dial(${secyOfMarketing})

Figure 17-1. Contexts define extensions that are localized and grouped logically

So, extensions 1 and 2 are actually defined several places in the dial-plan, but they have different meaning in different contexts. In the main context, extension 2 transfers the caller to the Marketing Department, but in the Sales context, extension 2 transfers the call to the secretary of marketing's phone.

17.3.1.4 Including contexts

In the Asterisk dial-plan configuration, it is possible to include one context within another, so that all of the extensions defined in a context are inherited by the context that includes it. Suppose you have this context:

 [voipco]     include => sales     exten => 102,1,Dial(${TEDSPHONE})     exten => 103,1,Dial(${KELLYSPHONE})     exten => 104,1,Dial(${MADDIESPHONE})

Note the include directive just below the section heading voipco that names this context. The include directive causes this context to implicitly inherit all of the directives of the sales context. So, from the voipco context, I can dial extensions 1 or 2 from the sales context in the previous example.

The default context in Asterisk is called, amazingly enough, default . This is where calls exist if no other context is specified.

17.3.1.5 The syntax of extensions

Notice the exten directives that begin each extension definition in the prior examples. In order to establish an extension in extensions.conf , you'll need this directive. The second half, the definition, contains three elements, separated by commas:

 exten =>   extension number   ,   priority   ,   application command

The first element of the definition is the extension numbergenerally, this means that a caller or a process has requested the extension by dialing it into their telephone set, or by signaling it during a call transfer. The second element is the priority, or the order in which the third element, the application command, is executed. Consider the following:

 [sales-after-hours]     exten => 110,1,Answer     exten => 110,2,Playback(sales-greeting)     exten => 110,3,Voicemail(110)     exten => 110,4,Hangup

Even though there are four lines of configuration, this is actually just a single extension (110) that makes use of several application commands. In the order defined by the priorities, extension 110 is answered by Asterisk, a sound file called sales-greeting is played to the caller, a voice mail message is recorded, and then the channel is hung up. In this way, the question, "What should the PBX do when someone dials 110?" is answered.

Besides user-defined extensions, Asterisk has a very important built-in extension, called the start extension , or simply S . This is the de facto extension for calls not associated with any other extensionlike calls coming in to the Asterisk PBX from a single-line X100P interface. Using the start extension in place of the extension number in a definition tells Asterisk how to handle these calls:

 [incoming]     exten => s,1,Dial(SIP/105)     exten => s,2,VoiceMail(105)

In this case, all unqualified calls are sent first to SIP phone 105 and, if that fails, to voice mailbox 105.

17.3.1.6 Extension pattern matching

Not all extensions are defined as static strings; some are defined as pattern-matched strings. If you're familiar with regexp or some other pattern-matching concept, this idea is nothing new. Consider the following:

 914403651964     914403652642

Two different strings of digits, right? Not always. When the following pattern mask is applied, the second string and the first string are both the same extension definition, even though they are actually different phone numbers. Take a look at the pattern that makes these two numbers become a single extension definition:

 _91440XXXXXXX

Like all Asterisk pattern masks, this one begins with the underscore character. It's purpose is to match any 12-digit phone number beginning with 91440 . When this pattern mask is used in the dial-plan, it causes all numbers that match its pattern to be treated as though they are all the same extension. The following extension definition matches all numbers dialed that begin with 91 and connects them to the public telephone company using the Zaptel channel provided by the X100P card, assuming the variable ${TELCO} contains the name of the Zaptel channel:

 exten => _91.,1,Dial(${TELCO}/${EXTEN})     exten => _91.,2,Congestion( )

The first priority of this extension is to use the Dial( ) application command to connect the caller's channel to the telephone company's line at the phone number contained in ${EXTEN} , a variable which always contains the most-recently dialed sequence of digits on the current channel. If this priority fails, the caller will hear a busy tone, as indicated by the Congestion( ) application command.

The wildcard characters that are used to match patterns consist of:

X matches any digit from 0 to 9.
Z matches any digit from 1 to 9.
N matches any digit from 2 to 9.
[126-9] matches any digit or letter in the brackets (in this example, 1, 2, 6, 7, 8, and 9)
. matches one or more alphanumeric characters.
1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , # , and * are always taken literally

Matched patterns can be any length. You might wonder why you would need extremely long patterns, but if you're using IVR applications, you may be collecting long data entries like credit card numbers (16 digits or more). While you can use other techniques to collect this data, extensions.conf is the only place where you can use powerful pattern matching for extensions. So routing calls based on credit card numbers, social security numbers and so on, is easy to do here. Pattern matching can be applied to both human-dialed and machine-signaled strings.

Asterisk pattern matching is relatively tame compared to regular expressions, which is supported by other soft-switch systems like SIP Express Router. But if you really need complex pattern matching with Asterisk, you can pass data as arguments to the Asterisk Gateway Interface (AGI), where you can use regexp in Perl or Python programs, and then pass it back into the dial-plan.

With the flexibility of Asterisk's application commands, variables, priorities, and contexts, there are nearly infinite ways of combining contexts and extension definitions in the dial-plan.

17.3.1.7 Special extensions

Special extensions are alphabetic characters that have a logical meaning in the dial-plan. They are used to describe scenarios in which an extension number doesn't exist, as when a call first enters the context from the outside world.

AAsterisk: This is where calls go if callers press the star key during a voice mail greeting.
iInvalid: This is where calls end up if the user has dialed an invalid DTMF or if the dial-plan has a bug that transfers a call to a non-existent extension.
s Start: The de facto extension that handles all incoming calls on channels that don't specify any other extension when first connecting.
hHangup: This is the extension you can program to handle what to do after the call has been disconnected.
tTimeout: This is the extension that handles programmed timeoutsthose time limits specified by dial-plan commands.
TAbsolute Timeout: The extension that handles programmed timeouts triggered by the AbsolouteTimeout dial-plan command.
oOperator: The extension that handles users who dial "0" in the current context.
talkTalk Detect: The extension that handles callers who've been detected talking using talk detection in the dial-plan.
fax: The special extension that receives calls when Asterisk has detected a fax signal. (This extension is able to receive faxes only when the SpanDSP fax module is installed; otherwise , it can be used to connect the call with a fax machine on an analog channel.)

17.3.2. String Processing in the Dial-Plan

Since the dial-plan defines call flows, it infers programmatic logic. So, when you set up a dial-plan, you're really programming the PBX. For that reason, Asterisk includes some syntactic capabilities that make your life as a PBX programmer simpler. One of the most important of these capabilities is string processing.

In most dial-plan commands, arguments are supplied as textual expressions. They may contain a mixture of literal values and variables. These expressions may be used in whole or in partthrough Asterisk's extensive chopping capabilities. Consider the following:

 exten => 1,1,SetVar(wholename=DestinysEnd)     exten => 1,2,SetVar(firstword=${wholename:1:8})

In this example, ${wholename} is assigned the value DestinysEnd . Then, in the next priority, ${firstword} is assigned the value of the first eight characters of ${wholename} . The syntax for string chopping and substringing is as follows :

 ${substring} = ${string:   offset   :   length   }

If the offset is less than 0, then it will be an offset from the end of the string, not the beginning. If length isn't supplied, the remainder of the string, from the offset on, will be included in the yielded substring. The following two examples produce identical results:

 exten => 1,1,SetVar(wholename=DestinysEnd)     exten => 1,2,SetVar(lastword=${wholename:9})     exten => 2,1,SetVar(wholename=DestinysEnd)     exten => 2,1,SetVar(lastword=${wholename:-1:4})

In either extension 1 or 2, ${lastword} is End .

17.3.2.1 Getting string lengths

The ${LEN} function measures the length of strings. Use it with SetVar to assign the length of an expression to a variable:

 exten => 1,1,DBGet(creditCard=${CALLERIDNUM}/creditcard)     exten => 1,2,SetVar(length=${LEN(${creditCard})})     exten => 1,3,GotoIf(${length}!=16?100:200)     exten => 1,100,Playback(thank-you)     exten => 1,101,Hangup( )     exten => 1,200,Playback(invalid-credit-card-number)     exten => 1,201,Goto(default,1,1)

In this example, a credit card number is pulled from the Asterisk database. If its length is 16, the system plays a thank you message. Otherwise, it plays an invalid message and changes contexts.

17.3.2.2 Concatenating strings

As in Perl and PHP quoted string expressions, multiple strings can be concatenated simply by putting them inline:

 exten => 1,1,SetVar(wholename=DestinysEnd)     exten => 1,2,SetVar(firstword=${wholename:1:8})     exten => 1,3,SetCIDName("Gilneas ${firstword}")     ; Caller ID Name is now "Gilneas Destiny"     exten => 1,4,SetCIDName("Gilneas${firstword}")     ; Caller ID Name is now "GilneasDestiny"

17.3.3. Dial-Plan Command Reference

Each extension you define in the dial-plan can have one of many commands. These commands are, as pointed out earlier, executed in order of their priority. Some of the commands are dependent upon one another. Here is a list of the most commonly used commands.

17.3.3.1 AbsoluteTimeout

 AbsoluteTimeout(   seconds   )

Sets absolute maximum time of call, in seconds. Once this time elapses, the call will be disconnected or handled by the t special extension, if one is defined in extensions.conf . Could be useful for calling card applications.

17.3.3.2 AddQueueMember

 AddQueueMember(  queue  [  channel  ])

Adds the current channel as a member to a call queue as configured in /etc/asterisk/queues.conf . If channel is specified, uses that channel instead of the current one.

17.3.3.3 ADSIProg

 ADSIProg(  script  )

Programs an ADSI (Analog Display Services Interface) script into an ADSI-capable phone. ADSI is a standard developed by the telecom industry for creating text-based interactive applications that augment traditional calling services.

17.3.3.4 AGI

 AGI(  program   arguments  )

Executes an Asterisk Gateway Interface program on the current channel. See "The Asterisk Gateway Interface," later in the chapter, for more information on AGI.

17.3.3.5 Answer

 Answer( )

Answers the incoming call on the current channel. Should be followed up with other commands or the calling party will just hear silence.

17.3.3.6 AppendCDRUserField

 AppendCDRUserField(  value  )

Appends the specified string value to the Call Detail Record user field.

Asterisk's Call Detail Record field map was spelled out in Project 5.1.

17.3.3.7 BackGround

 BackGround(  filename  )

Plays the specified GSM format sound file on the current channel and ends, giving control of the context to the next priority, if any, or goes back to the s extension if not. This can be used for IVR prompts like "Dial 1 for sales, 2 for support," and so on. If these numbers are valid within the context, then the context will handle them appropriately.

17.3.3.8 BackgroundDetect

 BackgroundDetect(  filename  )

Plays a sound file on the current channel while waiting for the caller to dial some digits or speak. Upon speaking, the user will be transferred to the special talk extension if it exists.

17.3.3.9 Busy

 Busy( )

Plays a busy signal on the current channel and waits for the caller/callee to disconnect.

17.3.3.10 ChangeMonitor

 ChangeMonitor(  filename  )

Changes the filename to which the audio dump of the current channel is being or will be sent, when used with Monitor .

17.3.3.11 ChanIsAvail

 ChanIsAvail(  channel  )

Checks to see if the specified channel is available, and store its name in ${AVAILCHAN} . Generally , this is used with the Cut command to reformat the channel name for use later in the dial-plan.

 ; Check if line 3 is available. If not, try line 2, then line 1.     exten => s,1,ChanIsAvail(Zap/3&Zap/2&Zap/1)     ; ${AVAILCHAN} may now contain the value: Zap/2-1     ; Strip off the session ID, putting just the channel number in ${MyChannel}     exten => s,2,Cut(MyChannel=AVAILCHAN,,1)     ; ${MyChannel} would now contain the value: Zap/2     ; Dial the intended number on this channel, which we'll assume is in ${PSTTNumber}     exten => s,3,Dial(${MyChannel}/${PSTNNumber})     exten => s,4,Hangup     ; If neither line is available, play a busy message.     exten => s,102,Playback(all-circuits-busy-now)     exten => s,103,Hangup

17.3.3.12 CheckGroup

 CheckGroup(  count  )

Determines whether the current channel's channel group is handling more than count calls. If so, redirects current call to priority equal to the current priority plus 101.

17.3.3.13 Congestion

 Congestion( )

Plays a congestion message to the caller/callee and waits for disconnect.

17.3.3.14 ControlPlayback

 ControlPlayback(  filename  ,  skip  ,  forward  ,  rewind  ,  stop  ,  pause  )

Plays the specified sound file, giving fast forward, rewinds and exit controls to the user on the current channel. Dialed digits are used to control playback. The arguments are the name of the GSM sound file, the number of milliseconds to use as an interval for rewinding and forwarding, and the dial-pad digits (including # and * ) that will be used to control the playback. Control of the call proceeds to the next priority when the end of the sound file is reached.

 exten => 2112,1,ControlPlayback(syrinx-song.gsm,4000,*,#,1,0)

17.3.3.15 Cut

 Cut(  expression  ,  delimiter  ,  fieldspec  )

Function that splits delimited strings. Could be used to split area codes from phone numbers.

 ; OldString is 'A&B&C&D'     exten => s,1,Cut(NewString=OldString,&,2)     ; NewString is 'B'

17.3.3.16 DBdel

 DBdel(  keytree  /  key  )

Drops the named key from the Asterisk database.

17.3.3.17 DBdeltree

 DBdeltree(  keytree  )

Drops a key tree from the Asterisk database.

17.3.3.18 DBget

 DBget(  varname  =  keytree  /  key  )

Gets a value from the Asterisk database. The following example gets a customer who is calling in to enter some digits and then uses those digits to look up the extension of that customer's service agent in the Asterisk database. Then, it transfers the call to that extension.

 [ServiceIVR]     exten => s,1,Answer( )     exten => s,2,Background(enter-your-8-digit-account-number.gsm)     exten => _NXXXXXXX,1,dbget(repExten=${EXTEN}/rep)     exten => _NXXXXXXX,2,Goto(${repExten})

17.3.3.19 DBput

 Dbput(  keytree  /  key  =  value  )

Sets a value in the Asterisk database. value can be a variable or a string literal.

17.3.3.20 DeadAGI

 DeadAGI(  program  )

Runs an AGI program on a channel after the call has ended.

17.3.3.21 Dial

 Dial(  channel  /  identifier  [,  timeout  ][,  options  ][,  url  ])

Makes an outbound call on the specified channel and bridges it with the current channel. Dial is one of the most capable, and most frequently used commands in Asterisk. Here are its arguments:

channel/identifier

In the form channel type/channel number/phone number . So, a using Zap/1/5551212 would dial 5551212 on the first Zaptel channel. Using SIP/105 would attempt to call the SIP peer defined as 105 on the local server. Using SIP/ted@sip.oreilly.com:5060 would attempt to open contact with the user ted at the oreilly.com SIP domain on the SIP-standard port of 5060.

timeout

Specifies the number of seconds to wait for an answer before giving up. As a rule, the current channel hears a ringback tone during this time.

options

A string of characters that represent different possibilities:

t: Allows the called user to transfer the call.
T: Allows the calling user to transfer the call.
r: Generates a ringback tone for the calling party immediately, rather than waiting until the remote system signals ringback. Avoid this option, as it stops real call progress indicators from being heard by the caller. Cannot be used with m .
R: Generates a ringback tone for the called party upon connection.
m: Plays music-on-hold to the caller until the call is answered. Cannot be used with r .
M(macro): Runs the macro called macro upon connection of the call.
P: Forces the caller to provide caller ID by way of Privacy Manager before connecting the call.
h: Permits the called party to hang up by pressing the star key ( * ).
H: Permits the caller to hang up by pressing the star key ( * ).
C: Resets the CDR for this call. This is similar to using the NoCDR command.
g: When the call is disconnected, continues to execute more commands in the current context.
A(filename): Plays a GSM sound file to the called party before connecting the call.
S(seconds): Automatically hangs up the call the specified number of seconds after connection.
D(digits): Once the callee answers, sends digits as a DTMF stream, then connects the call to the current channel. Should be used only on Zaptel channels or G.711 calls.
L(x[:y]): Time-limits the call to x ms, give an audible warning when y ms are left, repeated every z ms) Only x is required, y and z are optional. The voice heard for the warnings is that of a sound macro that's built in to Asterisk.
f: Forces caller ID to match the extension number of the outgoing channel. For example, some phone companies don't allow caller ID that doesn't match the trunk that it's being used with.

url

Finally, the optional url parameter will be sent to the called party's endpoint upon connection, if the endpoint supports URLs (some IP phones support this).

17.3.3.22 DigitTimeout

 DigitTimeout(   seconds   )

Sets the maximum time out, in seconds, allowed between dialed digits on the current channel only.

17.3.3.23 Directory

 Directory( )

Presents the user on the current channel with an IVR directory of voice mailboxes.

17.3.3.24 DISA

 DISA,  password   context

Gives the user direct inward system access capability, or the ability to obtain dial-tone and the ability to originate calls from the current channel in the specified context. User must enter a password using the dial-pad that matches the specified password.

17.3.3.25 Echo

 Echo( )

Immediately plays back the incoming audio signal back on the same channel it's coming from. Used to give testers an idea of how significant echo is on any given connection. Users can exit to the next priority by pressing the pound key ( # ).

17.3.3.26 EnumLookup

 EnumLookup(  extension  )

Looks up the specified extension number in ENUM and returns the SIP or TEL URI to the variable called ENUM. If a SIP entry exists, the next priority will be reached. If a TEL entry exists, the next priority plus 50 will be reached. If no entry is found, the next priority plus 100 will be reached. This example least-cost-routes all calls that start with a 9 to SIP via ENUM first before routing them to the PSTN.

 ; Any calls starting with 9 will undergo ENUM lookup.     exten=> _9[1-9]XXX.,1,BackGround(enum-doing)     exten=> _9[1-9]XXX.,2,EnumLookup(431${EXTEN:1})     ; ${EXTEN:1} is the dialed number with the leading 9 removed.     ;EnumLookupsets ${ENUM} on success. On failure jumps to priority+101.     exten=> _9[1-9]XXX.,3,BackGround(enum-successful)     exten=> _9[1-9]XXX.,4,Dial(${ENUM},30)     exten=> _9[1-9]XXX.,5,Goto(104)     ; No answer on SIP after 30 seconds, so dial the number on the PSTN     exten=> _9[1-9]XXX.,103,BackGround(enum-failed)     exten=> _9[1-9]XXX.,104,Dial,${TRUNK}/${EXTEN:1}

17.3.3.27 Festival

 Festival(  speech text  )

Says the specified text using the Festival voice synthesizer, if it's installed. The audio is sent to the current channel, and the user has the option of interrupting by dialing digits.

 exten => 200,1,Answer

17.3.3.28 Flash

 Flash( )

Sends a flash signal on the current Zaptel channel. Works only on Zaptel channels. Not useful unless the connected trunk has flash signaling features like call-waiting or three-way calling.

17.3.3.29 GetGroupCount

 GetGroupCount( )

Obtains the number of channels in the group the current channel belongs to and stores it in ${GROUPCOUNT} .

17.3.3.30 Goto

 Goto([  priority  ],[  extension  ],[  context  ])

Immediately changes the current channel to the specified context, priority, or extension.

 Goto(101) ; go to priority 101 in current extension     Goto(incoming,101) ; go to extension 101 in context 'incoming'     Goto(incoming,101,2) ; go to priority 2 in extension 101 in context 'incoming'

17.3.3.31 GotoIf

 GotoIf(  condition  ?  target1  [:  target2  ])

Go to target1 if the condition is true or to target2 if the condition is false.

When target1 and target2 are Goto -compatible targets, see "Goto" for target syntax.

condition is a string of the same expression syntax used for normal string processing within the dial-plan. This example does some simple ACD when an incoming call dials the 210 extension:

 ; See if area code is 216 and go to priority 3 or 5, depending.     Exten => 210,1,SetGlobalVar(myAreaCode=${CALLERIDNUM}:0:3)     exten => 210,2,GotoIf($[${myAreaCode}=216]?3:5)     exten => 210,3,Dial(${SPHONE1},15,rt)     exten => 210,4,Hangup     exten => 210,5,Dial(${PHONE2},15,rt)     exten => 210,6,Hangup

17.3.3.32 GotoIfTime

 GotoIfTime(  timecondition  ,[  priority  ],[  extension  ],[  context  ])

Immediately changes the current channel to the specified context, priority, or extension, if the supplied time condition is true. The time condition is provided in the format of time-based context includes, which are described in "Time-based context includes" in Chapter 12.

17.3.3.33 Hangup

 Hangup( )

Hangs up the current channel, ending the call, but going to the next priority for this extension, if one exists.

17.3.3.34 LookupBlacklist

 LookupBlacklist( )

If there's a caller ID for the caller on the current channel, looks up her name and number in the Asterisk database key tree called blacklist . If it exists, the command changes the priority to the next priority plus 100.

17.3.3.35 MailboxExist

 MailboxExist(  mailbox  )

Checks to see if the specified voice mailbox exists. Useful for intercepting misdialed numbers.

17.3.3.36 Math

 Math(  result  ,  operation  )

Performs a simple mathematical operation and assigns its value to the variable named by result . Here are some examples:

 exten => 1,1,Math(var,3*2) ; multiplication     exten => 1,2,Math(var,10-2) ; subtraction     exten => 1,3,Math(var,${EXTEN}>1000) ; greater-than     exten => 1,4,Math(var,${EXTEN}>=1000) ; greater-than or equal-to

The Math command is available only in Asterisk 1.01 and higher.

17.3.3.37 MeetMe

 MeetMe(  confno  [  options  ][  password  ])

Creates an Asterisk conference bridge. Requires Zaptel hardware to be installed, even if all bridge participants aren't on Zaptel channels. This is because the Zaptel hardware provides the conference mixing and timing functions needed for multiparty bridging. The configuration file /etc/meetme.conf is used to configure the Asterisk conference mixer. (Users without Zaptel hardware may consider compiling the ztdummy timing module instead.) options may be:

m: Sets monitor mode. Listen to conference only; current channel will not be heard by other participants.
t: Sets talk mode. Current channel will be heard by other participants, but will not be able to hear other participants.
p: Allows user on current channel to leave the conference by pressing the pound key ( # ).
X: Allows user on current channel to exit the conference by dialing a valid single-digit extension within the current context.
v: Uses video mode if the endpoint supports video.
q: Stops the conference mixer from playing alert sounds when users enter and leave the conference.
d: Creates a conference.
D: Creates a conference, prompting for PIN number. When prompted to establish the PIN, if the user wants no PIN created for the conference, he should press the pound key ( # ).
M: Plays music-on-hold when the conference has only a single participant.
e: Selects any existing empty conference (i.e., party line).
E: Selects any existing empty conference that doesn't require a PIN (i.e., party line).
b: Runs the AGI script specified in ${MEETME_AGI_BACKGROUND} . The script affects only Zaptel channels and is useless for SIP channels.
a: Sets admin mode, allowing the current channel to lock or unlock the conference. This has the effect of freezing the conference so that nobody can join it.
s: Enables the conference menu, which prompts the participant or conference admin appropriately. The conference menu is called by pressing the star key ( * ) during the conference. For participants, the menu allows the user to toggle mute on her channel only by dialing 1. For administrator participants, the menu adds the ability to toggle locking/unlocking of the conference by dialing 2.
A: Marks a user. Marked users can be used to trigger automatic teardown of the conference bridge when they leave and to prevent anybody from using the conference bridge until they connect.
x: Terminates the conference and disconnects all users when last marked user exits.
w: Waits until a marked user enters the conference before allowing any participants to send audio. While waiting, such participants will hear music-on-hold.

17.3.3.38 MeetMeAdmin

 MeetMeAdmin(  conference  ,  command  [,  user  ])

Issues conference administration commands to Asterisk conferences. The options are as follows:

K: Kicks all users from the conference. Conference will be destroyed if it were dynamically created.
k: Kicks the specified user from the conference.
L: Locks the conference.
l: Unlocks the conference.
M: Mutes the conference.
m: Unmutes the conference.

17.3.3.39 MeetMeCount

 MeetMeCount(  conference  ,[  variable  ])

Plays back the conference participant count on the current channel. If a variable is specified, records the count in that variable and skips playing back the count.

17.3.3.40 Milliwatt

 Millwatt( )

Generates a 1,000 Hz signal at 0 dBm on the current channel. This tone can be used by a lineman to measure transmissions on a phone line from a remote site, such as a residence or office for which the Asterisk server provides an FXO port.

17.3.3.41 Monitor

 Monitor(  format  ,  name  [,M])

Records the telephone conversation from the current channel to a sound file or caller and callee parts of the conversation to separate sound files. format is the desired sound file format. The default is wav . name is the base name of the output file(s), and the M flag can be added if you want SoxMix to automatically mix the two parts of the conversation into a single file upon termination of the call. The Sox package must be compiled and installed in order for this to work.

17.3.3.42 MP3Player

 MP3Player(  filename  )

Plays an MP3 sound file on the current channel. Playback can be stopped and the priority incremented by dialing any digit.

17.3.3.43 MusicOnHold

 MusicOnHold(  class  )

Plays hold music indefinitely from the specified class . Music-on-hold classes are established with simple directives in /etc/asterisk/musiconhold.conf . Normally these directives just point a certain class to a certain directory that contains MP3 files, but as this example shows, you can also use a streaming source:

 ; musiconhold.conf     default => mp3:/var/lib/asterisk/onhold,http://www.streamvoip.us/royalty-free:8000

The config needs a blank directory called onhold in /var/lib/asterisk using:

 # mkdir /var/lib/asterisk/onhold

17.3.3.44 NoCDR

 NoCDR( )

Insures Asterisk will not save any CDR data for the current call.

17.3.3.45 NoOp

 NoOp(  value  )

Echos values to the console for debugging purposes.

17.3.3.46 ParkedCall

 ParkedCall(  extension  )

Answers the parked call at the specified parked call extension.

17.3.3.47 Playback

 Playback(  filename  )

Answers the call on the current channel and plays the specified sound file.

17.3.3.48 Playtones

 Playtones(  tone  )

Play a tone from among those specified in /etc/asterisk/ indications .conf while executing other commands. Tone will continue to play indefinitely until StopPlaytones is called. Can also accept a tone list that consists of frequencies and durations, rather than a simple tone name. The tone list must be in the format specified in tones.conf .

17.3.3.49 PrivacyManager

 PrivacyManager( )

Requires a phone number to be entered on incoming calls when no caller ID signals are received. If the user doesn't enter the phone number, the priority advances to next plus 100. Currently supports only 10-digit phone numbers. Configured by /etc/asterisk/privacy.conf .

17.3.3.50 Queue

 Queue(  queue   options  )

Puts the current call into a call queue specified by queue . options is one or more of the following:

t: Permits the callee to transfer the call.
T: Permits the caller to transfer the call.
d: Marks the call as minimum delay, for use with modem calls, presumably on Zaptel channels only.
H: Permits the caller to hang up by pressing the star key ( * ).
r: Rings while queued instead of playing music-on-hold.

The hold queue configuration is stored in /etc/asterisk/queues.conf . Consult its comments for configuration instructions.

17.3.3.51 Random

 Random(  likelihood  ,  priority  )

Goes to a random priority based on the supplied likelihood, which is expressed as a percent. Useful for controlling traffic splitting.

17.3.3.52 Read

 Read(  variable  [  filename  ][  maxdigits  ])

Reads a string of digits from the user on the current channel, storing them in variable . Optionally, filename , a sound file, can be played prior to receiving the digits. maxdigits indicates the maximum number of digits that you'll allow, which can be no greater than 255.

 exten => s,1,Answer( )     exten => s,2,Read(credCardNumenter-cred-num16)     exten => s,3,Read(credExpDateenter-exp-date4)     exten => s,4,Playback(thank-you)     exten => s,5,Noop(${credCardNum} ${credExpDate})

17.3.3.53 ResetCDR

 ResetCDR( )

Resets CDR data for the current call, as if it were beginning now.

17.3.3.54 ResponseTimeout

 ResponseTimeout(  seconds  )

Sets maximum timeout awaiting a dialing activity from the user. Default is 15 seconds, after which time the call will be transferred to t or hung up if t doesn't exist.

17.3.3.55 Ringing

 Ringing( )

Plays a ringback tone on the current channel.

17.3.3.56 Rpt

 Rpt( )

Allows ham radio systems and two-way repeaters to be interfaced with Asterisk through special hardware, so that radio calls can be signaled from the PBX. For more information, visit http://zapatatelephony.org/app_rpt.html.

17.3.3.57 SayAlpha

 SayAlpha(  string  )

Audibly says the string , one character at a time, on the current channel. Besides letters and number, SayAlpha has sounds for #, *,-,+, !, @, and $.

17.3.3.58 SayDigits

 SayDigits(  string  )

Audibly says the string, ignoring any non-numeric characters.

17.3.3.59 SayNumber

 SayNumber(  string  )

Uses full-word pronunciation to say the number, from 0 to 99 million. If the string is 405120 , the caller will hear "Four hundred five thousand, one hundred twenty."

17.3.3.60 SayPhonetic

 SayPhonetic(  string  )

Says the string using NATO phonetic pronunciation. Recommend using Festival instead for most applications.

17.3.3.61 SayUnixTime

 SayUnixTime([  unixtime  ],  timezone  ,  format  )

Says the date and time on the current channel. unixtime is a Unix timestamp, the number of seconds since January 1, 1970. If unixtime is omitted, the current time is used. timezone is a timezone consistent with the configuration of /usr/share/zoneinfo . format is a string that uses the strftime(3) function's convention. For more information, see the manpage for strftime(3) .

17.3.3.62 SendDTMF

 SendDTMF(  digits  )

Sends the DTMF digits on the current channel.

17.3.3.63 SendText

 SendText(  text  )

Sends a text message to the endpoint on the current channel. Works only with devices that support text messaging, such as SIP clients .

17.3.3.64 SendURL

 SendURL(  url  [,wait])

Sends the device on the current channel a web page URL to display, if it can. Devices that don't support HTML transport will result in going to the next priority plus 100.

17.3.3.65 SetAccount

 SetAccount(  account  )

Sets the CDR account code to be used for this call. Also, stores the account code in ${ACCOUNTCODE} for further reference within the dial-plan.

17.3.3.66 SetCallerID

 SetCallerID(  newcallerid  )

Overrides the existing caller ID string for the current call. SetCallerID is overridden if SIP peer has a fromuser configuration.

17.3.3.67 SetCDRUserField

 SetCDRUserField(  user  )

Sets the name of the user to appear in the CDR record for this call.

17.3.3.68 SetCIDName

 SetCIDName(  name  )

Sets the caller ID name for originating calls from the current channel, using, for example, the Dial command.

17.3.3.69 SetCIDNum

 SetCIDNum(  number  )

Sets the caller ID number for originating calls from the current channel.

17.3.3.70 SetGlobalVar

 SetGlobalVar(  variable  =  value  )

Sets a global dial-plan variable to the value supplied. Value can be another variable's value. Here are some examples:

 ; set the name of a PSTN trunk to a Zaptel channel name     exten => _N*,1,SetGlobalVar(PSTNtrunk=Zap/1)     ; store the extension in a variable     exten => _N*,2,SetGlobalVar(CallInProgress=${EXTEN})     exten => _N*,3,Noop(${CallInProgress})

17.3.3.71 SetLanguage

 SetLanguage(  language  )

Changes localization setting for sound playback of digits, characters, and fully pronounced numbers.

17.3.3.72 SetMusicOnHold

 SetMusicOnHold(  class  )

Sets default hold music class for the current channel.

17.3.3.73 SetVar

 SetVar(  variable  =  value  )

Sets a local variable (local to this call) to the value supplied.

17.3.3.74 SIPdtmfMode

 SIPdtmfMode(  option  )

Changes DTMF mode during a SIP call in progress on the current channel. option is one of these three: info , inband , or rfc2833 . inband should be used only with G.711.

17.3.3.75 SMS

 SMS(  options  )

Sends and receives SMS (short messaging service) messages from within the dial-plan. For more information, see http://www.smsclient.org/.

17.3.3.76 SoftHangup

 SoftHangup(  channel  )

Ends the call on the specified channel. To hang up the current channel, use Hangup( ) instead.

17.3.3.77 StopMonitor

 StopMonitor( )

Stops monitoring a channel that is currently being monitored using Monitor( ) .

17.3.3.78 StopPlaytones

 StopPlaytones( )

Stops playing a tone list or a tone. Returns audio on the current channel to the call in progress.

17.3.3.79 StripLSD

 StripLSD(  number  )

Strips the least-significant digitsi.e., from the right of the current extension. The number of digits to strip is specified by number . So, if extension 5241900 stripped down to 1900 at the first priority, processing would continue at the second priority of extension 1900.

17.3.3.80 StripMSD

 StripMSD(  number  )

Strips most significant digitsi.e., from the left of the current extension. The number of digits to strip is specified by number . Continues processing at the next priority in the new extension. So, if extension 5241900 stripped down to 524 at the first priority, processing would continue at the second priority of extension 524.

17.3.3.81 System

 System(  command  )

Executes a system command in a shell as the user that runs Asterisk. Can substitute variables within the command line, as in this example, which creates a new directory for every call before recording it into a sound file in that directory using Monitor( ) :

 exten => s,1,Answer( )     exten => s,2,System('mkdir /var/spool/calls/${exten}')     exten => s,3, Monitor(   WAV   ,   /var/spool/calls/${exten}/call   ,M)

17.3.3.82 Transfer

 Transfer(  extension  )

Transfers the call on the current channel to the specified extension.

17.3.3.83 VoiceMail

 VoiceMail([  options  ]  box  )

Connects the current channel to a local voice mailbox specified by box . options is one or more of the following (or none of them):

s: Skips the voice mail instructions ("Please leave your message after the tone. When done, hang up, or press the pound key.") and just plays the subscriber's greeting.
u: Causes the unavailable message to be played (instead of the busy message). By default, the message says, "The person at extension 2112 is unavailable," but the voice mail subscriber may record his own unavailable message if he wants.
b: Causes the busy message to be played (instead of the unavailable message). By default, the message says, "The person at extension 2112 is busy," but can be overridden with a recorded message by the subscriber.

17.3.3.84 VoiceMailMain

 VoiceMailMain(  box  )

Connects the current call to the generic voice mail subscriber greeting. If box is given, the voice mail server assumes the specified subscriber is trying to log in to retrieve messages or manage her voice mailbox.

Chapter 14 describes how to configure Asterisk's voice mail system using the /etc/asterisk/voicemail.conf file.

17.3.3.85 Wait

 Wait(  seconds  )

Waits for the number of seconds specified before proceeding to the next priority.

17.3.3.86 WaitExten

 WaitExten(  duration  )

Waits for the number of seconds specified for the user on the current channel to enter a valid extension; otherwise, proceeds to next priority. Also, can accept the duration in decimal numbers for tenths of a second (1.2, 10.5, 0.5, etc.).

17.3.3.87 WaitMusicOnHold

 WaitMusicOnHold(  seconds  )

Identical to Wait( ) , but plays the music-on-hold class associated with this call or context while the caller is waiting.

17.3.3.88 Zapateller

 Zapateller( )

Sends the do-not-call signal to incoming callers.

17.3.3.89 ZapBarge

 ZapBarge(  channel  )

Allows caller to clandestinely listen in on another channel's call in progress, as long as it's a Zaptel channel. Neither party in the conversation will know that the call is being monitored by the "barging" caller. If you don't provide a channel name, the caller will be prompted for one. Entering 1# would listen in on Zap/1, while entering 3# would listen in on Zap/3.

17.3.3.90 ZapScan

 ZapScan( )

Scans Zaptel channels to monitor calls. Pressing # moves to the next channel. Pressing the star key ( * ) exits to the next priority.