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.

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

Routing a call requires two pieces of information: the phone number being routed and a destination for that phone number. In our example, we will use a DID number 8005551212. Our destination will be user 1000. Replace these sample numbers with the appropriate values for your setup.

All calls that come in to the FreeSWITCH server from outside (as well as internal calls that are not authenticated) are initially handled in the public context (dialplan contexts were discussed in more detail in this chapter's introduction) of the XML dialplan. Once the call hits the public context, we try to match the destination_number field. The destination_number is generally the DID number (see the There's more… section for some caveats). Once we match the incoming number, we set the domain_name channel variable to the default domain value, and then transfer the call to user 1000. (FreeSWITCH is domain-based in a way similar to e-mails. Most systems have only a single domain, though FreeSWITCH supports multiple domains.) The actual transfer happens with this dialplan entry:

<action application="transfer" data="1000 XML default"/>

In plain words, this tells FreeSWITCH to transfer the call to extension 1000 in the default context of the XML dialplan. The default context contains the Local_Extension that matches "1000" as destination_number and handles the calls to users' telephones.

Keep in mind that the expression for destination_number must match what the provider sends to FreeSWITCH, not necessarily what the calling party actually dialed. There are providers that send DID information in various formats, such as these:

The expression must match what the provider sends. One way to accomplish this is to have a few optional characters in the pattern. This pattern matches all three formats you just saw:

<condition field="destination_number" expression="^\+?1?(8005551212)$">

The \+? value means "optionally match the literal + character," and the 1? value means "optionally match the literal digit 1." Now our pattern will match all of the three formats that are commonly used in North America. (Technically, our pattern will also match +8005551212, but we are not concerned about that. However, the pedantic admin might be, so they can use the ^(\+1)?1?(8005551212)$ pattern instead.)

Making outbound calls requires you to know the numbering format that your provider requires. For example, do they require all 11 digits for US dialing? Or will they accept 10? In our example, we're going to assume that our provider will accept a 10-digit format for US dialing (for example, without the international prefix "1").

Routing outbound calls is simply a matter of creating a dialplan entry:

Assuming you have a phone set up on the default context, your regular expression will match any destination_number that follows the US dialing format (10 or 11 digits), and send the call to our_sip_provider in a 10-digit format. The format in regexp is as follows: optional "1", then one digit between 2 and 9, then two digits, then one digit between 2 and 9, and finally six digits. Only the part after the optional digit "1" is captured by the parentheses and passed down in the $1 variable.

The regular expression matching in FreeSWITCH allows the privilege of having very powerful conditions. You can also match caller_id_number to route calls from a user calling from extension 1011 out to the second gateway called our_second_sip_provider, while everyone else will be sent through our_sip_provider. Consider the following alternative outbound_calls.xml file:

<include>
<extension name="outbound_calls_from_1011">
<condition field="caller_id_number" expression="^1011$"/>
<condition field="destination_number"
   expression="^1?([2-9]\d{2}[2-9]\d{6})$">
<action application="bridge" data="sofia/gateway/our_second_sip_provider/$1"/>
</condition>
</extension>
<extension name="outbound_calls">
<condition field="destination_number"
    expression="^1?([2-9]\d{2}[2-9]\d{6})$">
<action application="bridge" data="sofia/gateway/our_sip_provider/$1"/>
</condition>
</extension>
</include>

Note that we have two extensions. The first one tries to match the caller_id_number field to the value 1011. If it matches 1011, then the call gets sent to the our_second_sip_provider gateway. Otherwise, the next extension is matched and the call goes to the our_sip_provider gateway. Note that we use $1 to capture the matching value in the conditions' expressions. In each case, we capture exactly 10 digits, which correspond to the area code (three digits), exchange (three digits), and phone number (four digits). These are North American Numbering Plan (NANP) numbers. The regular expressions used to capture the format of dialed digits vary, depending upon the country.

Open conf/dialplan/default.xml in a text editor or create a new XML file in the conf/dialplan/default/ subdirectory.

Add a comma-separated list of endpoints to your bridge (or originate) application. For example, to ring userA@local.pbx.com and userB@local.pbx.com simultaneously, use an extension like this:

<extension name="ring_simultaneously">
<condition field="destination_number" expression="^(2000)$">
<action application="bridge" data="{ignore_early_media=true}sofia/internal/userA@local.pbx.com,sofia/internal/userB@local.pbx.com"/>
</condition>
</extension>

Putting comma-separated endpoints into the argument to bridge causes all the endpoints in that list to be dialed simultaneously. It sounds simple; however, there are several factors to consider when ringing multiple devices simultaneously in a real environment. The bridge application will connect the call to whoever sends the media first. This includes early media (ringing). To put this in other words, if you bridge a call to two parties and one party starts sending a ringing signal back to you, that will be considered media and the call will be connected to that party. Ringing of the other phones will cease.

If you notice that calls always go to a specific number on your list of endpoints versus ringing all numbers, or that all phones ring for a moment before ringing only a single number, it means that your call may be getting bridged prematurely because of early media. Notice that we added ignore_early_media=true at the beginning of the dial string. As its name implies, ignore_early_media tells the bridge application not to connect the calling party to the called party when receiving early media (such as a ringing or busy signal). Instead, bridge will only connect the calling party to the called party who actually answers the call. In most cases, it is useful to ignore early media when ringing multiple endpoints simultaneously.

In some scenarios, you may also wish to ring specific devices for a limited amount of time. You can apply the leg_timeout parameter to each leg of the bridge to specify how long to ring each endpoint like this:

<action application="bridge" data="[leg_timeout=20]sofia/internal/userA@local.pbx.com,[leg_timeout=30]sofia/internal/userB@local.pbx.com"/>

In this example, the userA user's phone will ring for a maximum of 20 seconds, while the userB user's phone will ring for a maximum of 30 seconds.

This method of calling multiple parties works well for a small number of endpoints. However, it does not scale to dozens or more users. Consider using a FIFO queue in such an environment (FreeSWITCH's mod_fifo is discussed at length at http://freeswitch.org/confluence/display/FREESWITCH/mod_fifo).

Open conf/dialplan/default.xml in a text editor or create a new XML file in the conf/dialplan/default/ subdirectory.

Add a pipe-separated list of endpoints to your bridge (or originate) application. For example, to ring userA@local.pbx.com and userB@local.pbx.com sequentially, use an extension like this:

<extension name="ring_sequentially">
<condition field="destination_number" expression="^(2001)$">
<action application="bridge" data="{ignore_early_media=true}sofia/internal/userA@local.pbx.com|sofia/internal/userB@local.pbx.com"/>
</condition>
</extension>

Putting pipe-separated endpoints in the argument to bridge (or originate) causes all the endpoints in that list to be dialed sequentially. The first endpoint on the list that is successfully connected will be bridged, and the remaining endpoints will not be dialed. There are several factors to consider when ringing multiple devices sequentially.

Notice that we added ignore_early_media=true at the beginning of the dial string. As its name implies, ignore_early_media tells the bridge application not to connect the calling party to the called party when receiving early media (such as a ringing or busy signal). Instead, bridge will only connect the calling party if the called party actually answers the call. In most cases, you will need to ignore early media when dialing multiple endpoints.

Handling different failure conditions can be a challenge. FreeSWITCH has a number of options that let you tailor bridge and originate to your specific requirements.

<action application="bridge" data="{ignore_early_media=true,monitor_early_media_fail=user_busy:2:480+620!destination_out_of_order:2:1776.7}sofia/internal/userA@local.pbx.com|sofia/internal/userB@local.pbx.com"/>

condition_name:number_of_hits:tone_detect_frequencies

destination_out_of_order:2:1776.7.

<action application="bridge" data="[leg_timeout=10]sofia/internal/userA@local.pbx.com|[leg_timeout=15]sofia/internal/userB@local.pbx.com"/>

<action application="bridge" data="{originate_continue_on_timeout=true}[leg_timeout=10]sofia/internal/userA@host|[leg_timeout=15]sofia/internal/userB@host"/>

<extension name="ring_sequentially">
<condition field="destination_number" expression="^(2001)$">
<action application="set" data="continue_on_fail=true"/>
<action application="set" data="hangup_after_bridge=true"/>
<action application="bridge" data="{ignore_early_media=true}sofia/internal/userA@local.pbx.com"/>
<action application="log" data="INFO call to userA failed."/>
<action application="bridge" data="{ignore_early_media=true}sofia/internal/userB@local.pbx.com"/>
<action application="log" data="INFO call to userB failed."/>
</condition>
</extension>

The first thing you need to do to take advantage of enterprise originate is to fully understand regular originate. Originate is the term used to indicate making an outbound call. Although there is an originate command that can be used at fs_cli, the method by which you mostly use the originate command is with the bridge dialplan application.

You will need to open conf/dialplan/default.xml in a text editor or edit a new XML file in the conf/dialplan/default/ subdirectory.

The usage of enterprise originate is similar to the ring simultaneously example, but an alternate delimiter (:_:) is used:

<extension name="enterprise_originate">
<condition field="destination_number" expression="^(2000)$">
<action application="bridge" data="{ignore_early_media=true}sofia/internal/userA@local.pbx.com:_:{myoption=true}sofia/internal/userB@local.pbx.com"/>
</condition>
</extension>

<extension name="enterprise_originate2">
<condition field="destination_number" expression="^(2001)$">
<action application="bridge" data="{ignore_early_media=true}sofia/internal/userA@local.pbx.com,sofia/internal/userB@local.pbx.com:_:sofia/internal/userC@local.pbx.com,sofia/internal/userD@local.pbx.com"/>
</condition>
</extension>

The entire input string is broken down into smaller strings based on the :_: symbol.

Each of those smaller strings is fed to the regular originate engine in parallel, and the first channel to answer will be bridged to the caller. Once one endpoint answers, the rest of the calls in the enterprise will be canceled.

Enterprise originate has a few special aspects to consider when using it to place calls.

<action application="bridge" data="<ignore_early_media=true>{myvar=inner1}[who=userA]sofia/internal/userA@local.pbx.com,[who=userB]sofia/internal/userB@local.pbx.com:_:{myvar=inner2}[who=userC]sofia/internal/userC@local.pbx.com,[who=userD]sofia/internal/userD@local.pbx.com"/>

To learn more about originate and enterprise originate, look at some other examples in this chapter and study the default dialplan distributed with FreeSWITCH. There are several examples of the many things you can do when placing outbound calls found in conf/dialplan/default.xml.

Determine the parameters for your routing. In this example, we will define business hours as Monday through Friday from 8:00 a.m. to 5:00 p.m. Additionally, we will include a day_part variable to reflect morning (midnight to noon), afternoon (noon to 6:00 p.m.), and evening (6:00 p.m. to midnight).

Start at the beginning of your dialplan by following these steps:

The Time of day, day of week setup extension defines two channel variables, namely office_status and day_part. Note the use of inline="true" in our set applications. These allow immediate use of the channel variables in later dialplan condition statements. Every call that hits this dialplan context will now have these two channel variables set (they will also show up in CDR records if you need them). You may have also noticed continue="true" in the extension tag and break="never" in the condition tags. These tell the dialplan parser to keep looking for more matches when it would otherwise stop doing so. For example, without continue="true", when the dialplan matches one of the conditions in the Time of day, day of week setup extension, it stops looking at any more extensions in the dialplan. In a similar way, the break="never" attribute tells the parser to keep looking for more conditions to match within the current extension (by default, when the parser hits a failed condition, it stops processing any more conditions within the current extension).

Our sample extension number is 5001. Note the action it takes:

<action application="execute_extension" data="5001_${office_status}"/>

This sends the call back through the dialplan looking for a destination_number of 5001_open or 5001_closed. We have defined these destinations with the "office is open" and "office is closed" extensions respectively. Now we can play different greetings to the caller: one when the office is open and a different one when the office is closed. As a nice touch, for all calls, we play a sound file that says "Good morning", "Good afternoon", or "Good evening", depending on what the value in the day_part channel variable is.

You may be wondering why we did not simply use a condition to test office_status for the open value, and then use action tags for "office open" and anti-action tags for "office closed". There is nothing preventing us from doing this. However, what if you need to have an office status other than "open" or "closed"? For example, what if you have an office that needs to play a completely different greeting during lunch time? This is difficult to accomplish with only anti-action tags, but with our example, it is very simple. Let's make it a bit more challenging by adding a lunch period that runs from 11:30 a.m. to 12:30 p.m. We cannot use hour="11.5-12.5", but we do have another value we can test — time-of-day. This parameter lets us define periods in the day at a granularity of minutes, or even seconds. The value range can be 00:00 through 23:59 or 00:00:00 through 23:59:59. Consider this new Time of day, day of week setup snippet:

<extension name="Time of day, day of week setup" continue="true">
<condition wday="2-6" hour="8-16 break="never">
<action application="set" data="office_status=open" inline="true"/>
<anti-action application="set" data="office_status=closed" inline="true"/>
</condition>
<condition wday="2-6" time-of-day="11:30-12:30" break="never">
<action application="set" data="office_status=lunch" inline="true"/>
</condition>
      ....

Notice that we need to explicitly define the weekend, since we cannot rely on a simple Boolean "open" or "closed" condition. However, we now have a new office_status of "lunch" available to us. We define an additional extension to handle this case:

<extension name="office is at lunch">
<condition field="destination_number" expression="^(5001_lunch)$">

Add the specific dialplan actions for handling calls during the office's lunch hour, and you are done. You can add as many new office statuses as you need.

Be sure that you have your DIDs and users configured. In this example, we will use testuser as the username, with a phone number of 4158867999, and our domain will be my.phoneco.test.

Create a dialplan extension specifically for handling calls to the DID number, and use some regular expression syntax to parse out the information. Here is an example:

<extension name="call_4158867999">
<condition field="destination_number" expression="^\+?1?4158867999$"/>
<condition field="${sofia_contact(testuser@local.pbx.com)}" expression="^[^\@]+(.*)">
<action application="bridge" data="sofia/external/4158867999$1"/>
</condition>
</extension>

You would typically send calls to testuser using the bridge command with an argument of user/testuser. In this scenario, however, you would wish to call the testuser's registered endpoint and replace testuser with a phone number, which is 4158867999 in our example. To do this, you must retrieve the testuser's current dial string and remove the username, replacing it with the DID number.

In this example, we leverage the sofia_contact API and some regular expression magic. The first condition simply matches the user's DID phone number. We only want to act if the destination number is 4158867999. The interesting stuff happens in the second condition. The field is ${sofia_contact(testuser@local.pbx.com)}. By wrapping an API call in ${}, the dialplan literally executes the API and uses the result as the field value. If we go to fs_cli and type sofia_contacttestuser@local.pbx.com, we get the result, which is something like this:

sofia/external/johndoe@12.34.56.7;fs_nat=yes

The ^[^\@]+(.*) regular expression pattern is applied against this value. The result is that everything after, and including, the @ sign is placed in the $1 variable. In our example, $1 contains @12.13.56.7;fs_nat=yes. Finally, we execute bridge with the sofia/external/4158867999$1 dial string. With $1 expanded, our destination is as follows:

sofia/external/4158867999@12.34.56.7;fs_nat=yes

We have successfully replaced testuser with 4158867999, while preserving the necessary IP address and parameters for contacting the server, and sent the call to the proper destination.