Advanced multiple endpoint calling with enterprise originate
You've seen many ways to ring multiple destinations with many options, but in some cases this is still not good enough. Say you wanted to call two destinations at once but each of those two destinations was a separate set of simultaneous or sequential destinations.
For instance, you want to call Bill and Susan at the same time, but Bill prefers you to try his cell first, then try all of his landlines at the same time. Susan prefers you to call her desk first, then her cell, and then her home. This is a complicated problem and the solution to that problem is called enterprise originate. The term enterprise is used to indicate an increased level of indirection, dimension, or scale. Basically, you are doing everything the originate
syntax has to offer, but you are doing entire originates in parallel in a sort-of super originate
.
Getting ready
The first thing you need to do to take advantage of enterprise originate is to fully understand the regular originate. Originate is the term used to indicate making an outbound call. Although there is an originate
command that can be used at the fs_cli
, the method by which you mostly use the originate
command is with the bridge
dialplan application.
Tip
The bridge application versus the originate command
Why do we talk about a regular originate
when discussing the bridge
application? Are not the bridge
application and the originate
command completely different? No! This is a common misconception, and it is incorrect. The bridge
application is used in the dialplan, but it does exactly the same thing that the originate
command does – it creates a new call leg. In fact, bridge
and originate
use exactly the same code in the FreeSWITCH core. The only difference between the two is where they are used. The originate
command is used at the fs_cli
to create a new call leg. The bridge
application is used in the dialplan to create a new call to which an existing call leg can be connected or bridged.
You will need to 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...
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/[email protected]:_:{myoption=true}sofia/sip/[email protected]"/> </condition> </extension> <extension name="enterprise_originate2"> <condition field="destination_number" expression="^(2001)$"> <action application="bridge" data="{ignore_early_media=true}sofia/internal/[email protected],sofia/sip/[email protected]:_:sofia/internal/[email protected],sofia/internal/[email protected]"/> </condition> </extension>
How it works...
The entire input string is broken up 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.
There's more...
Enterprise originate has a few special aspects to consider when using it to place calls.
Setting variables
As you know, you can use the {var=val}
syntax to define special variables to be set on all channels produced by originate
and [var=val]
to define variables per leg in a call with many simultaneous targets. Enterprise originate uses these as well, but remember that each string separated by the :_:
delimiter is its own self-contained instance of originate so {var=val}
becomes local only to that single originate string. If you want to define variables to be set on every channel of every originate
, you must define them at the very beginning of the string using the <var=val>
notation. This indicates that you should pass these variables to every leg inside every originate
. Consider the following enterprise originate:
<action application="bridge" data="<ignore_early_media=true>{myvar=inner1}[who=userA]sofia/internal/[email protected],[who=userB]sofia/sip/[email protected]:_:{myvar=inner2}[who=userC]sofia/internal/[email protected],[who=userD]sofia/internal/[email protected]"/>
At first glance, this may seem confusing, but when you break it down, you can see what the values of the variables are for each channel. This table shows the values:
Channel |
${ignore_early_media} |
${myvar} |
${who} |
---|---|---|---|
true |
inner1 |
userA | |
true |
inner1 |
userB | |
true |
inner2 |
userC | |
true |
inner2 |
userD |
Once you know which syntax to use, it becomes a simple matter to set channel variables for individual legs, inside originates, or the entire enterprise originate.
Ringback
Unlike the regular originate, signaling cannot be passed back from one of the inner originates because there are too many call paths open to properly handle it. Therefore, when using bridge
with the enterprise originate, you must define the ringback
variable if you want to send a ring tone back to the caller.
See also
To learn more about originate and enterprise originate, look at some of the 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
.