Ringing multiple endpoints sequentially (simple failover)

Sometimes it is necessary to ring additional endpoints, but only if the first endpoint fails to connect. The FreeSWITCH XML dialplan makes this very simple.

Getting ready

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

How to do it...

Add a pipe-separated list of endpoints to your bridge (or originate) application. For example, to ring [e-mail] and [e-mail] 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/[e-mail]|sofia/sip/[e-mail]"/> 
  </condition>
</extension>

How it works...

Putting pipe-separated endpoints in the argument to bridge causes all of the endpoints in that list to be dialed sequentially. The first endpoint on the list that is successfully connected will be bridged and the other 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 sequentially.

There's more...

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

Handling busy and other failure conditions

For example, when calling a user who is on the phone, one service provider might return SIP message 486 (USER_BUSY) whereas many providers will simply send a SIP 183 with SDP, and a media stream with a busy signal. In the latter case, how will the bridge application know that there is a failure if it is ignoring the early media that contains the busy signal? FreeSWITCH gives us a tool that allows us to monitor early media even while "ignoring" it.

Consider two very common examples of failed calls where the failure condition is signaled in-band:

• Calling a line that is in use

• Calling a disconnected phone number

These conditions are commonly communicated to the caller via specific sounds: busy signals and special information tones, or SIT tones. In order for the early media to be meaningful, we need to be able to listen for specific tones or frequencies. Additionally, we need to be able to specify that certain frequencies mean different kinds of failure conditions (this becomes important for reporting, as in call detail records or CDRs). The tool that FreeSWITCH provides us is a special channel variable called monitor_early_media_fail. Its use is best illustrated with an example:

<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/[e-mail]|sofia/sip/[e-mail]"/>

Here we have a bridge application that ignores early media and that sets two failure conditions, one for busy and one for destination out of order. We specify the name of the condition we are checking, the number of hits, and the frequencies to detect. The format for monitor_early_media_fail is:

condition_name:number_of_hits:tone_detect_frequencies

The user_busy condition is defined as user_busy:2:480+620. This condition looks for both 480 Hz and 620 Hz frequencies (which is the U.S. busy signal) and if they are detected twice, then the call will fail. The exclamation point (!) is the delimiter between conditions. The destination_out_of_order condition is defined as:

destination_out_of_order:2:1776.7. 

This looks for two occurrences of 1776.7 Hz, which is a common SIT tone frequency in the U.S (there is a nice introductory article on SIT tones at http://en.wikipedia.org/wiki/Special_information_tones). If 1776.7 Hz is heard twice, then the call will fail as destination out of order.

When using monitor_early_media_fail, only the designated frequencies are detected. All other tones and frequencies are ignored.

Handling no answer conditions

Handling a no answer condition is different from busy and other in-band errors. In some cases, the service provider will send back a SIP message 480 (NO_ANSWER) whereas others will send a ringing signal in the early media until the caller decides to hang up. The former scenario is handled automatically by the bridge application. The latter can be customized with the use of special timeout variables:

• call_timeout: Sets the call timeout for all legs when using bridge

• originate_timeout: Sets the call timeout for all legs when using originate

• leg_timeout: Sets a different timeout value for each leg

• originate_continue_on_timeout: Specifies whether or not the entire bridge or originate operation should fail if a single call leg times out

By default, each call leg has a timeout of 60 seconds and bridge/originate will stop after any leg times out. The three timeout variables allow you to customize the timeout settings for the various call legs. Use call_timeout when using the bridge application and use originate_timeout when using the originate API. Use leg_timeout if you wish to have a different timeout value for each dialstring. In that case, use the [leg_timeout=###] notation for each dialstring:

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

Use originate_continue_on_timeout to force bridge or originate to continue dialing even if one of the endpoints fails with a timeout:

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

Keep in mind that, by default, a timeout (that is, a no answer) will end the entire bridge or originate if you do not set originate_continue_on_timeout to true.

One other thing to keep in mind is handling cases where you are calling a phone number that has voicemail. For example, if you are trying to implement a type of "find me, follow me" and one of the numbers being called is a mobile phone with voicemail, you need to decide if you want that phone's voicemail to answer your call. If it does answer, then the bridge will be completed. If you do not want to have the voicemail answer and end the bridge (so that your bridge will keep dialing the other endpoints), then be sure to set the leg_timeout to a relatively low value. If the voicemail picks up after 15 seconds, then you may wish to set leg_timeout=12. In most cases, you will need to make several test calls to find the best timeout values for your various endpoints.

Using individual bridge calls

In some cases, you may find that it is helpful to make a dial attempt to a single endpoint and then do some processing prior to dialing the next endpoint. In these cases, the pipe-separated list of endpoints will not suffice. However, the FreeSWITCH XML dialplan allows you to do this in another way. Consider this excerpt:

<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/[e-mail]"/>
    <action application="log" data="INFO call to userA failed."/>
    <action application="bridge" data={ignore_early_media=true}sofia/internal/[e-mail]"/>
    <action application="log" data="INFO call to userB failed."/>
  </condition>
</extension>

The key to this operation is the highlighted lines. In the first one, we set continue_on_fail to true. This channel variable tells FreeSWITCH to keep processing the actions in the extension even if a bridge attempt fails. After each bridge attempt, you can then do some processing. Note, too, that we set hangup_after_bridge to true. This is done so that the dialplan does not keep processing after a successful bridge attempt. (For example, if the call to userA was successful, we would not want to call userB after userA hung up.) You may add as many additional bridge endpoints as needed.

See also

• The Ringing multiple endpoints simultaneously and Advanced multiple endpoint calling with enterprise originate sections in this chapter