Home Cloud & Networking FreeSWITCH 1.6 Cookbook

FreeSWITCH 1.6 Cookbook

By Giovanni Maruzzelli , Anthony Minessale II
books-svg-icon Book
Subscription FREE
eBook + Subscription €14.99
eBook €25.99
Print + eBook €32.99
READ FOR FREE Free Trial for 7 days. €14.99 p/m after trial. Cancel Anytime! BUY NOW BUY NOW BUY NOW
What do you get with a Packt Subscription?
This book & 7000+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook + Subscription?
Download this book in EPUB and PDF formats
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook?
Download this book in EPUB and PDF formats
Access this title in our online reader
DRM FREE - Read whenever, wherever and however you want
Online reader with customised display settings for better reading experience
What do you get with video?
Download this video in MP4 format
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with Audiobook?
Download a zip folder consisting of audio files (in MP3 Format) along with supplementary PDF
READ FOR FREE Free Trial for 7 days. €14.99 p/m after trial. Cancel Anytime! BUY NOW BUY NOW BUY NOW
Subscription FREE
eBook + Subscription €14.99
eBook €25.99
Print + eBook €32.99
What do you get with a Packt Subscription?
This book & 7000+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook + Subscription?
Download this book in EPUB and PDF formats
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook?
Download this book in EPUB and PDF formats
Access this title in our online reader
DRM FREE - Read whenever, wherever and however you want
Online reader with customised display settings for better reading experience
What do you get with video?
Download this video in MP4 format
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with Audiobook?
Download a zip folder consisting of audio files (in MP3 Format) along with supplementary PDF
  1. Free Chapter
    Routing Calls
About this book
Publication date:
July 2015
Publisher
Packt
Pages
190
ISBN
9781785280917

 

Chapter 1. Routing Calls

In this chapter, we will discuss routing calls in various scenarios, as follows:

  • Internal calls

  • Incoming DID (also known as DDI) calls

  • Outgoing calls

  • Ringing multiple endpoints simultaneously

  • Ringing multiple endpoints sequentially (simple failover)

  • Advanced multiple endpoint calling with enterprise originate

  • Time-of-day routing

  • Manipulating SIP To: headers on registered endpoints to reflect DID numbers

 

Introduction


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.

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, 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 [1025]

Understanding these basic principles will help you create effective dialplan extensions.

Note

For more tips on using regular expressions, be sure to visit http://freeswitch.org/confluence/display/FREESWITCH/Regular+Expression.

Important dialplan contexts in the default configuration

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 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:

  • 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 (via "hash" commands) the local calls database to allow call return and call pickup

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).

The public context

The 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.

The features context

The features context is used to make certain features available for calls that are in progress. Consider this excerpt from 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 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 dx." In conf/dialplan/features.xml, there 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.

 

Internal calls


Calling local extensions is very simple once you know what needs to happen. In this case, we will see how to add a new user and make their phone available for calling.

Getting ready

If you are using the default configuration, then users 1000 through 1019 are preconfigured, both in the directory and the dialplan. To add a user beyond this range to the directory, it is generally easier to run the add_user script, found in the FreeSWITCH source directory under scripts/perl. For example, to add user 1020 to the directory, launch this script from the FreeSWITCH source directory, specifying the user ID on the command line:

scripts/perl/add_user 1020

You can also specify a range of users:

scripts/perl/add_user –-users=1020-1029

You will see a note about the number of users added to the directory. If you have the Regexp::Assembly CPAN module installed, then the script will also generate a couple of sample regular expression patterns, which you can then use in the dialplan. For our example, we added a range of users from 1020 to 1029 to the directory, and then we'll add them to the dialplan.

How to do it...

  1. Open the conf/dialplan/default.xml file in a text editor. Locate the Local_Extension entry:

    <extension name="Local_Extension">
    <condition field="destination_number"
    expression="^(10[01][0-9])$">
  2. Edit the expression in the <condition> tag to account for our new users. The ^(10[012][0-9])$ expression pattern will do what we need (look closely to see the difference). The new line will be as follows:

    <condition field="destination_number"
    expression="^(10[012][0-9])$">
  3. Save the file and then execute reloadxml from fs_cli.

Tip

Downloading the example code

You can download the example code files for all Packt Publishing books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

How it works...

Local_Extension is the default dialplan entry that allows directory users to be called. Remember that simply adding a user to the directory does not mean that the user can be dialed. (However, it does usually mean that the user can make outbound calls.) So, in order for your new user to be reachable, you need to add their user ID to the dialplan. By default, Local_Extension has a regular expression that will match 1000, 1001, and so on up to 1019. After adding that number range, it is necessary to modify the regular expression to account for those new numbers. In our example, we added user IDs 1020 through 1029, so we need to match these. We use this regular expression:

^(10[012][0-9])$

This matches 1000 through 1029. Let's say we have added another block of user IDs with the range from 1030 to 1039. We can modify our regular expression to catch them as well:

^(10[0123][0-9])$

It is considered best practice not to add a large range of dialable numbers to Local_Extension without having the corresponding users in the directory. Doing so can make troubleshooting dialplan issues more difficult.

As a reminder, be sure to execute the reloadxml command each time you modify the regular expression (the changes you make to your XML configuration files will not take effect until they are loaded into the memory, which is what the reloadxml command does).

See also

  • The Creating users section in Chapter 5, PBX Functionality

             
About the Authors
  • Giovanni Maruzzelli

    Giovanni Maruzzelli (gmaruzz@OpenTelecom.IT) is heavily engaged with FreeSWITCH. In it, he wrote a couple of endpoint modules, and he is specialized in industrial grade deployments and solutions. He's the curator and coauthor of FreeSWITCH 1.6 Cookbook (Packt Publishing, 2015), and of Mastering FreeSWITCH (Packt Publishing, 2016) He's a consultant in the telecommunications sector, developing software and conducting training courses for FreeSWITCH, SIP, WebRTC, Kamailio, and OpenSIPS. As an Internet technology pioneer, he was the cofounder of Italia Online in 1996, which was the most popular Italian portal and consumer ISP. Also, he was the architect of its Internet technologies Italia Online (IOL). Back then, Giovanni was the supervisor of Internet operations and the architect of the first engine for paid access to il Sole 24 Ore, the most-read financial newspaper in Italy, and its databases (migrated from the mainframe). After that, he was the CEO of the venture capital-funded company Matrice, developing telemail unified messaging and multiple-language phone access to e-mail (text to speech). He was also the CTO of the incubator-funded company Open4, an open source managed applications provider. For 2 years, Giovanni worked in Serbia as an Internet and telecommunications investment expert for IFC, an arm of the World Bank. Since 2005, he has been based in Italy, and he serves ICT and telecommunication companies worldwide.

    Browse publications by this author
  • Anthony Minessale II

    Anthony Minessale II is the primary author and founding member of the FreeSWITCH Open Source Soft-Switch. Anthony has spent around 20 years working with open source software. In 2001, Anthony spent a great deal of time contributing code to the Asterisk PBX and has authored numerous features and fixes to that project. In 2005, Anthony started coding a new idea for an open source voice application. The FreeSWITCH project was officially open to the public on January 1 2006. In the years that followed, Anthony has been actively maintaining and leading the software development of the FreeSWITCH project. Anthony also founded the ClueCon Technology Conference in 2005, and he continues to oversee the production of this annual event.

    Browse publications by this author
FreeSWITCH 1.6 Cookbook
Unlock this book and the full library FREE for 7 days
Start now