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.
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 [email protected] and [email protected] 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/[email protected]|sofia/internal/[email protected]"/>
</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.
For example, when calling a user who is on the phone, one service provider might return SIP message 486 (USER_BUSY), whereas many providers might simply send a SIP 183 with SDP and a media stream with a busy signal. In the latter, 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 with 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/internal/[email protected]"/>Here, we have a bridge application that ignores early media and 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 as follows:
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 USA busy signal), and if they are detected twice, then the call will fail. The exclamation mark (!) is the delimiter between the conditions. The destination_out_of_order condition is defined like this:
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 USA (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 a no-answer condition is different from busy and other in-band errors. In some cases, the service provider will send back SIP message 480 (NO_ANSWER), whereas others will send a ringing signal (SIP 183) 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 usingbridgeoriginate_timeout: Sets the call timeout for all legs when usingoriginateleg_timeout: Sets a different timeout value for each legoriginate_continue_on_timeout: Specifies whether or not the entirebridgeororiginateoperation should fail if a single call leg times out
By default, each call leg has a timeout of 60 seconds and bridge, or 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 dial string. In that case, use the [leg_timeout=###] square bracket notation for each dial string:
<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/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.
Another 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 whether 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 the voicemail to answer and end the bridge (so that your bridge will keep dialing the remaining endpoints), then be sure to set 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.
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/[email protected]"/> <action application="log" data="INFO call to userA failed."/> <action application="bridge" data="{ignore_early_media=true}sofia/internal/[email protected]"/> <action application="log" data="INFO call to userB failed."/> </condition> </extension>
Key to this operation are the highlighted lines. In the first of them, 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 do some processing. Note, however, 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 you need.