Routing calls is at the core of any FreeSWITCH server. There are many techniques for accomplishing the surprisingly complex task of connecting one phone to another. However, it is important to make sure that you have the basic tools necessary to complete this task.
The most basic component of routing calls is the dialplan, which is essentially a list of actions to perform depending upon which digits were dialed (as we will see in some of the recipes in this book, there are other factors that can affect routing of calls). The dialplan is broken down into one or more contexts. Each context is a group of one or more extensions. Finally, each extension contains specific actions to be performed on the call. The dialplan processor uses regular expressions, which are a pattern-matching system used to determine which extensions and actions to execute.
To make best use of the recipes in this chapter, it is especially important to understand how to use regular expressions and the three contexts in the default configuration.
<extension name="example"> <condition field="destination_number" expression="^(10\d\d)$"> <action application="log" data="INFO dialed number is [$1]"/>
This example demonstrates the most common uses of regular expressions in the dialplan: matching against the
destination_number field (that is, the digits that the user dialed) and capturing, using parentheses, the matched value in a special variable named
$1. Let's say that a user dials 1025. Our example extension will match 1025 against the
^(10\d\d)$ pattern and determine that this is indeed a match. All actions inside the
condition tag will be executed. The
action tag in our example will execute the
log application. The
log application will then print a message to the console, using the
INFO log level, which will be in green text by default. The value in
$1 is expanded (or interpolated) when printed:
2015-02-22 15:15:50.664585 [INFO] mod_dptools.c:1628 dialed number is 
Understanding these basic principles will help you create effective dialplan extensions.
For more tips on using regular expressions, be sure to visit http://freeswitch.org/confluence/display/FREESWITCH/Regular+Expression.
Each of these contexts serves a purpose, and knowing about them will help you leverage their value for your needs.
The most used context in the default configuration is the
default context. All users whose calls are authenticated by FreeSWITCH will have their calls passing through this context, unless there have been modifications. Some common modifications include using ACLs or disabling authentication altogether (see the The public context section that follows). The
default context can be thought of as internal in nature; that is, it services users who are connected directly to the FreeSWITCH server, as opposed to outside callers (again, see the The public context section).
Many characteristics related to PBX (Private Branch Exchange) are defined in the
default context, as are various utility extensions. It is good to open
conf/dialplan/default.xml and study the extensions there. Start with simple extensions such as
show_info, which performs a simple
info dump to the console, and
vmain, which allows a user to log in to their voicemail box.
A particularly useful extension to review is
Local_Extension. This extension does many things, as follows:
Many of the techniques employed in
Local_Extension are discussed in this chapter (see the The features context section for a discussion on the in-call features found in this extension).
public context is used to route incoming calls that originate from outside the local network. Calls that initially come to the
public context are treated as untrusted. If they are not specifically routed to an extension in the
default context, then they are simply disconnected. As mentioned before, disabling authentication or using ACLs to let calls into the system will route them into the
public context (this is a security precaution, which can be overridden if absolutely required). We will use the
public context in the Incoming DID (also known as DDI) calls recipe.
<action application="bind_meta_app" data="1 b s execute_extension::dx XML features"/>
This is just one of several features that are enabled for the recipient of the call. The
bind_meta_app application listens on the audio stream for a touch-tone * followed by a single digit. The preceding example is a blind transfer. If the called user dials *1, then the
execute_extension::dx XML features command is executed. In plain words, this command says, "Go to the
features context of the XML dialplan and execute the extension whose destination number is
conf/dialplan/features.xml, there is the following extension:
<extension name="dx"> <condition field="destination_number" expression="^dx$"> ...
This process demonstrates several key points:
Calls can be transferred from one dialplan context to another
featurescontext logically isolates several extensions that supply in-call features
bind_meta_appdialplan application is one of the means of allowing in-call features
Understanding that calls can flow from one context to another even after they are in progress is an important concept to grasp when addressing your call routing scenarios.