Chapter 5. Understanding the XML Dialplan
The Dialplan is a crucial part of any FreeSWITCH installation. Indeed, any PBX must have a Dialplan, sometimes called a numbering plan, in order to handle the routing of calls. In simple terms, a Dialplan is a list of instructions on where to route a call. For example, when a user picks up a phone and dials 1000, how does the system know what to do with that call? The default Dialplan knows to connect the calling party to the telephone registered as with user id 1000. However, the Dialplan can do much more than merely connect the calling and called parties. In many cases, the Dialplan will contain instructions on what the call should do and how it should behave.
In the previous chapter, we made small modifications to the Dialplan. In this chapter, we will build upon that foundation and introduce the basics of routing and controlling calls as we discuss the following topics:
Overview of the XML Dialplan
Contexts, extensions, and actions
Conditions, patterns...
FreeSWITCH XML Dialplan elements
The default FreeSWITCH XML Dialplan is contained in three main files and two directories, located in conf/dialplan/:
default.xml—The primary FreeSWITCH Dialplan configuration
public.xml—Handles calls coming in to FreeSWITCH from another location
features.xml—A special context for handling specific dialing features
default/—Files in this directory get included in the default context
public/—Files in this directory get included in the public context
The default XML configuration has many instructions for routing calls, all of which make use of the basic building blocks of a Dialplan: contexts, extensions, conditions, and actions. A context is a logical grouping of one or more extensions. An extension contains one or more conditions that must be met. Conditions contain actions that will be performed on the call, depending on the whether the condition is met or not. Before discussing these building blocks further, though, let's revisit some of the concepts we...
How Dialplan processing works
Understanding the Dialplan is easier if you can visualize what happens when a call comes in. Often, we hear expressions like "the call traverses the Dialplan" or "the call hits the Dialplan". What exactly does that mean? Let's walk through the processing of a call, so that we can really understand what XML Dialplan is doing.
The Dialplan has two phases:
parsing and executing. The Dialplan parser looks for extensions to execute. When it finds a matching extension, it then adds the actions (or anti-actions) to a list of tasks. When the parser finishes looking for extensions, the execution phase begins, and the actions in the task list are performed.
A good way to see all of this in action is to watch the FreeSWITCH console in debug mode while making a test phone call. Launch fs_cli, make a test call to 9196 (music on hold), and then hang up the phone. Scroll back in your terminal and look for a line that looks something like the following:
Let's create a brand new extension. Start by opening the following XML file we created in Chapter 4, The User Directory: conf/dialplan/default/01_Custom.xml. This file will contain the custom extensions that we create from now on.
Tip
Always begin your custom Dialplan filenames with a digit sequence. The reason for this is that the XML parser reads the XML files in ASCII order. The last file in conf/dialplan/default/ that we want parsed is 99999_enum.xml. This file contains the ENUM extension which is used as a "last resort" if the dialed number does not match any other extensions. See http://wiki.freeswitch.org/wiki/Mod_enum for more information.
A Dialplan XML file can contain one or more extension definitions. The only restriction is that the file should begin and end with the XML tags <include> and </include> respectively.
Our new extension will be simple, but it will also demonstrate the power and flexibility of the FreeSWITCH Dialplan. The extension...
Important Dialplan applications
FreeSWITCH has about one hundred different Dialplan applications. However, a few of them are particularly important because they are used so frequently.
The
bridge application connects two endpoints together.
Argument syntax: <target_endpoint>[,<target_endpoint>][|<target_endpoint>]
Endpoints separated by commas are dialed simultaneously. Endpoints separated by pipes are dialed sequentially. The first endpoint to answer receives the call, and dialing to all other endpoints is discontinued.
Examples:
See "Dialstring Formats" later in this chapter.
The
playback application simply plays an audio file to the caller. Files can be in many formats. The sound and music files included in FreeSWITCH are all .wav files.
Argument syntax: absolute path to a sound file or relative path to an installed sound file...
Before we leave our discussion of the Dialplan, it would be good to consider one more topic: Dialstrings. A
Dialstring is exactly what it sounds like‑ a string of characters that defines a destination to be dialed by FreeSWITCH. All Dialstrings have a specific syntax. The syntax varies depending upon the type of endpoint being dialed. The most important types of Dialstring in FreeSWITCH are those for Sofia, because they represent how we dial SIP endpoints. However, as we will see there are several different kinds of Dialstrings. They are used primarily in two places, which are as follows:
Bridging an existing call leg in the Dialplan with the bridge application
Creating a new call leg at the CLI with the
originate command
Tip
Dialstring syntax is the same whether using bridge or originate.
Let's learn a bit more about Dialstrings by considering a few examples, starting with some sofia Dialstrings. The basic sofia Dialstring takes two different formats:
Completing this chapter is an important milestone for the beginner. Understanding the concepts presented here is a large part of being able to configure and maintain a FreeSWITCH server. A number of topics were discussed. They are as follows:
The basic hierarchy of the FreeSWITCH XML Dialplan:
The Dialplan consists of one or more contexts
Contexts consist of one or more extensions
Extensions contain one or more conditions
Conditions usually have one or more actions or anti-actions
Regular expressions and pattern matching
An introduction to the concept of channel variables
How Dialplan parsing and processing works
Creating our own custom extension
A list of some of the more common and useful Dialplan applications
Having these basic skills, you should now be able to create truly useful extensions that do more than merely connect one telephone user to another. Although the Dialplan is very powerful and flexible, it is not in and of itself an IVR engine or a programming language. FreeSWITCH has...
