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.

Add a pipe-separated list of endpoints to your bridge (or originate ) application. For example, to ring [email protected] and [email protected] sequentially, use an extension like this:

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.

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.

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/[email protected]|sofia/sip/[email protected]"/> 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/[email protected]|[leg_timeout=15]sofia/internal/[email protected]"/> 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/[email protected]|[leg_timeout=15]sofia/internal/[email protected]"/> 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.