FreeSwitch Dialplan XML

FreeSwitch is an open-source telephony application capable of being a class 4 or class 5 soft-switch as well as a PBX. Freeswitch runs on Linux, OSX, Windows NT/XP/CE, *BSD and many other platforms. It is licensed under the MPL (Mozilla Public License) version 1.0. FreeSwitch was written from the ground up as a new application and is not a fork of any other application.


The XML Dialplan is the default dialplan that is used. This creates a flexible dialplan, and allows for 3rd party tools to be quickly and easily created since there is an abundance of software that can manipulate dialplans. XML is also easily and readily edited by hand without requiring any special tools other than a text editor.

The XML dialplans allow for Perl Regular Expression matching on fields, which gives you a lot of flexibility in a standardized format which some may be accustomed to already, and others can readily find documentation on how to work with Perl Regular Expressions.

Anatomy of the XML Dialplan

There are several elements in the XML dialplan. In general you have context, extension, condition and action. Each is processed in order until you reach the action tag which tells freeswitch what action to perform. You are not limited to only one condition or action tag for a given extension.


Contexts are a logical grouping of extensions. You may have multiple extensions contained within a single context. WE NEED MORE INFORMATION ON WHAT A CONTEXT IS AND HOW ITS SET AND USED

The context tag has a required parameter of 'name'. There is one reserved name 'any' which matches any context. The name is to assist you in identifying the context.


Extensions are destinations for a call. They are given a name and a grouping of conditions and actions are contained within them instructing FreeSwitch what to do.

The extension tag has a required parameter of 'name'. This is just a arbitrary name that you give this extension to assist you in identifying it later. It has an optional argument of 'continue' which is set to true or false. If continue is true even if a match is found, FreeSwitch will continue to execute the following extensions for matches once this extension has completed its actions. The default is to not continue.


Conditions are pattern matching tags that help FreeSwitch decide if the current call should be processed in this extension or not. When matching conditions against the current call you have several variables that you can compare against.
  • dialplan
  • context
  • caller_id_name
  • caller_id_number
  • ani
  • ani2
  • rdnis
  • destination_number
  • uuid
  • network_addr
  • source
  • chan_name

In addition to the above you can also do variables using the syntax ${variable} or api functions using the syntax %{api} {args}

You have two tags that are required for conditions, 'field' which contains the variable you wish to match against and 'expression' which contains the regular expression to apply. Using () in a regular expression will result in $1, $2 ... $N being populated appropriately which can be used later in the action tag. There is an optional tag 'break' which can take the values on-true, on-false, always and never. This lets you select how FreeSwitch will continue to process the extension, if for example you have break="on-false" and a condition does not match, FreeSwitch discontinues processing any more conditions in this extension and moves onto the next.

Action and Anti-Action

Action tags are executed when there is a match, anti-action tags are executed when there is not a match. There are two arguments to action tags, application and data. Application is the registered application to execute, for example bridge, data is the argument to that application for example exosip/123@myserver. When you use anti-action tags you cannot use $1 since the regexp did not match, that value will not be populated.


<context name="default">
<extension name="demo">
<condition field="destination_number" expression="^(\d{7})$">
<action application="bridge" data="exosip/$1@myprovider"/>
<anti-action application="playback" data="number-is-invalid.wav"/>

Created by: trixter, Last modification: Wed 29 of Nov, 2006 (02:59 UTC) by mmurdock
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+