Book Image

FreeSWITCH Cookbook

By : Raymond Chandler, Darren Schreiber, Anthony Minessale II, Michael Collins
Book Image

FreeSWITCH Cookbook

By: Raymond Chandler, Darren Schreiber, Anthony Minessale II, Michael Collins

Overview of this book

FreeSWITCH is an open source telephony platform designed to facilitate the creation of voice, chat, and video applications. It can scale from a soft-phone to a PBX and even up to an enterprise-class softswitch.In the FreeSWITCH Cookbook, members of the FreeSWITCH development team share some of their hard-earned knowledge with you in the book's recipes. Use this knowledge to improve and expand your FreeSWITCH installations.The FreeSWITCH Cookbook is an essential addition to any VoIP administrator's library.The book starts with recipes on how to handle call routing and then discusses connecting your FreeSWITCH server to the outside world.It then teaches you more advanced topics like CDR handling, practical examples of controlling FreeSWITCH with the event socket, and configuring many features commonly associated with a PBX installation.
Table of Contents (12 chapters)
FreeSWITCH Cookbook
About the Authors
About the Reviewers


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 what digits were dialed (as we will see in some of the recipes in this book, there are other factors that can affect the routing of calls). The dialplan is broken up into one or more contexts. Each context is a group of one or more extensions . Finally, each extension contains specific actions that can be performed on the call. The dialplan processor uses regular expressions, which is a pattern-matching system, to determine which extensions and actions to execute.

To make the 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.

Regular expressions

FreeSWITCH uses Perl-compatible regular expressions (PCRE) for pattern matching. Consider this dialplan excerpt:

<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 the matched value in a special variable named $1. Let's say that a user dials 1025; our example extension would match 1025 against the pattern ^(10\d\d)$ and determine that this is indeed a match. All actions inside the condition tag would be executed. The action in our example would execute the log application. The log application will then print a message to the console, using the INFO log level, which, by default, will be in green text. The value in $1 is expanded (or interpolated) when printed out:

2011-01-09 13:38:31.864281 [INFO] mod_dptools.c:1152 dialed number is [1025]

Understanding these basic principles will enable you to create effective dialplan extensions. For more tips on using regular expressions, be sure to visit

Important dialplan contexts in the default configuration

As previously mentioned, contexts are logical groups of extensions. The default FreeSWITCH configuration contains three contexts:

  • default

  • public

  • features

Each of these contexts serves a purpose, and knowing about them will help you leverage their value for your needs.

The default context

The most-used context in the default configuration is the default context. All users whose calls are authenticated by FreeSWITCH will have their calls pass through this context, unless there have been modifications. Some common modifications include using ACLs or disabling authentication altogether (see The public context section that follows). The default context can be thought of as "internal" in nature, that is, it services the users who are connected directly to the FreeSWITCH server, as opposed to outside callers. (again, see The public context section that follows).

Many of the PBX-related (Private Branch Exchange) features are defined in the default context, as are various utility extensions. It is good to open conf/dialplan/default.xml and study the extensions in there. Start with simple extensions like show_info, which performs a simple info dump to the console, and vmain, which allows a user to log into his/her voicemail box.

A particularly useful extension to review is the Local_Extension. This extension does many things:

  • Routes calls between internal users

  • Sends calls to the destination user's voicemail on a no answer condition

  • Enables several in-call features with bind_meta_app

  • Updates the local calls database to allow for a call return and call pickup

Many of the techniques employed in the Local_Extension are discussed in this chapter (see also The features context below for a discussion of the in-call features found in this extension).

The public context

The public context is used to route incoming calls that originate from outside the local network. Calls that initially come in to the public context and are treated as untrusted—if they are not specifically routed to an extension in the default context, then they are simply disconnected. As mentioned above, disabling authentication or using ACLs to let calls into the system will route them into the public context (this is a security precaution that can be overridden if absolutely required). We will use the public context in the recipe Incoming DID calls.

The features context

The features context is used to expose certain features for calls that are in progress. Consider this excerpt from the Local_Extension in conf/dialplan/default.xml:

<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 above example is a blind transfer. If the user dials *1, then the command execute_extension::dx XML features is executed. In plain language, this command says, "Go to the features context of the XML dialplan and execute the extension whose destination number is dx". In conf/dialplan/features.xml is the following extension:

<extension name="dx">
  <condition field="destination_number" expression="^dx$">

The dx extension accepts some digits from the user and then transfers the caller to the destination that the user keyed in.

This process demonstrates several key points:

  • Calls can be transferred from one dialplan context to another

  • The features context logically isolates several extensions that supply in-call features

  • The bind_meta_app dialplan 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.