Include statements

Include statements
	Chapter 2. Dialplan Basics

Includes are a powerful tool for simplifying and organizing larger dialplans. Using an include statement, you can include other contexts in the current context.

Syntax

include => name-of-the-other-context

Example

[general]

[sales]
include => internal
include => external

[internal]
exten => 2000,1,Dial(SIP/2000)

[external]
exten => 17005551212,1,Dial(SIP/5551212)

Order of execution when using include statements

Asterisk will always look for a match in the current context before referencing any included contexts. If a matching entry is found, that entry is used. If no matching entry is found, Asterisk will look for a match in the first included context, then the next, and so on. It is also possible to have nested includes; that is, includes within includes.

In case of doubt, you can verify what entry Asterisk is using to handle a call by entering dialplan show number@name-of-context in the Asterisk CLI.


	Users of Asterisk 1.2 use show dialplan instead of dialplan show.

A few examples:

[general]

[sales]
include => internal
include => external

[internal]
exten => 2000,1,Dial(SIP/2000)

[external]
exten => 17005551212,1,Dial(SIP/5551212)

Say we want to understand how Asterisk is handling a call to 2000 in the sales context. To do that, we enter dialplan show 2000@sales in the CLI:

*CLI> dialplan show 2000@sales
[ Included context 'internal' created by 'pbx_config' ]
  '2000' =>         1. Dial(SIP/2000)                             [pbx_c
onfig]

-= 1 extension (1 priority) in 1 context. =-
*CLI>

If we then expand the sales context like so:

[general]

[verkauf]
include => internal
include => external

exten => 2000,1,Answer()
exten => 2000,2,Playback(hello-world)
exten => 2000,3,Hangup()

[internal]
exten => 2000,1,Dial(SIP/2000)

[external]
exten => 17005551212,1,Dial(SIP/5551212)exten => 03012345678,1,Dial(SIP/
03012345678)

We will see this CLI output::

*CLI> dialplan show 2000@sales
[ Context 'sales' created by 'pbx_config' ]
  '2000' =>         1. Answer()                                   [pbx_c
onfig]
                    2. Playback(hello-world)                      [pbx_c
onfig]
                    3. Hangup()                                   [pbx_c
onfig]
[ Included context 'internal' created by 'pbx_config' ]
  '2000' =>         1. Dial(SIP/2000)                             [pbx_c
onfig]


-= 2 extensions (4 priorities) in 2 contexts. =-
*CLI>

Asterisk will play the hello-world sound file and not send the call to 2000, even though the include occurs first in the dialplan. This is because Asterisk will always look for a match in the current context before checking the included contexts.

Time-conditional include statements

An include statement can be made conditional upon the time of day. This makes it easy to implement different day and night behaviors.

Syntax

include => context|<time>|<day>|<day-of-month>|<month>

The day and month are specified using the first three letters of the full name. For example, weekdays are specified mon, tue, wed, thu, fri, sat, sun, and months are specified jan, feb, mar, apr, etc. The time is specified in 24 hour format.

Example

A business is open from 9:00 a.m. until 5:00 p.m. Monday to Friday and from 9:00 a.m. to 2:00 p.m. Saturday. The dialplan would look like this:

; Day
 include => open|09:00-17:00|mon-fri|*|*
 include => open|09:00-14:00|sat|*|*
include => closed

[open]
exten => 2000,1,Dial(SIP/2000)

[closed]
exten => 2000,1,VoiceMail(2000,u)


Pattern Matching	\|	Chapter 3. Programming in the dialplan