Page tree
Skip to end of metadata
Go to start of metadata

About

Bridge a new channel to the existing one.Generally used to route an incoming call to one or more endpoints. Multiple endpoints can be dialed simultaneously or sequentially using the comma and pipe delimiters, respectively.


 Click here to expand Table of Contents

Usage

<action application="bridge" data="endpoint/gateway/gateway_name/address"/>

Examples

Endpoint examples expressed as API commands:

 

Simple endpoint:

Multiple endpoints simultaneously (call blast) -- no limit to concurrency, first one to answer wins

Multiple endpoints sequential -- no limit to failover number

Setting Variables for the B-leg simple example using brackets:

Setting Variables for the B-leg thread-global using braces:

Setting Variables for the B-leg with enterprise originate for multiple threads:

Dialplan Examples

Bridge an incoming call to an external SIP address or termination provider.

Bridge the incoming call to extension 100 and 101. The '%' is used instead of the @ to indicate that the endpoints are registered locally. Separate multiple endpoints with a comma. The ${sip_profile} variable is defined in freeswitch.xml.

To dial multiple contacts all at once:

To dial multiple contacts one at a time:

Extra parameters: for instance, if you are dipping to get an LRN lookup:

or

or

will result in:

However, you will also get 12135551212;rn=12135550000;npdi=yes in the To: parameter. Thus, to get rid of that you can append the carat (^) as follows:

Options

You can set different options to modify the behavior of the call. Be sure to set the option before executing the application. Here are some examples:

Timeout

The maximum number of seconds to wait for an answer state from a remote endpoint.

No Media Mode

See full discussion at Bypass Media Overview.

No media mode is an SDP Passthrough feature that permits two endpoints that can see each other (no funky N.A.T.) to connect their media sessions directly while FreeSWITCH maintains control of the SIP signaling. This is useful if you have two end-points that need to use a codec that is currently not supported in FreeSWITCH (video) or if you are using FreeSWITCH in a high performance walled garden network and want to minimize the RTP handling FreeSWITCH is doing to maximize call traffic.

When set, the media (RTP) from the originating endpoint is sent directly to the destination endpoint and vice versa. The signaling (SIP) for both endpoints still goes through FreeSWITCH, but the media is point-to-point.

Before executing the bridge action you must set the "bypass_media" flag to true.

bypass_media must only be set on the A leg of a call, for example:

Setting Outgoing CallerID

If you are using FreeSWITCH as a PBX you may want to control the outgoing CallerID that is sent to the PSTN or your SIP provider. Your SIP Provider will most likely require you to use a specific CallerID number (or a userid instead). The following example sets them before executing the bridge action. See more about caller ID privacy options.

Sending Ringback

You may want to simulate ringback to your internal users while you dial a provider, or you may need to force a ringback back upstream when you are dialing multiple extensions and cannot determine what call treatment you will need to provide yet. In order to accomplish this, you need to set a chanvar before going to the bridge application.

Note that you can use another ring than ${us-ring}, but it would have to be defined in your configuration (typically in vars.xml).

Calling multiple destinations

By using commas to separate the addresses, bridge will dial them simultaneously. Using pipes, it'll dial one at a time. Use :_: to separate multiple destinations to be dialled in a multi-threaded manner (this is referred to as "Enterprise Origination") - this gives more flexibility (and avoids the "Only calling the first element in the list in this mode" warning)

If you need to set different channel variables for each destination, you may prefix the destinations with [] and the variables inside the brackets. Example:

Note: by default when bridging, the first endpoint to provide media (as opposed to actually answering) will win, and the other endpoints will stop ringing. For internal endpoints, this usually doesn't matter. However, in the case of cell phone providers, any custom music that plays for the caller while ringing counts as media. In some cases, the ringing sound itself is media. If your bridge command includes a cell phone number and your internal endpoints stop ringing as soon as the cell phone starts, you will need to enable the 'ignore_early_media' option:

Implementing Failover

Failover for your outbound gateway is easy to implement at bridge time using the | separator:

Setting the options ping parameter on the gateway in the sip_profiles definition will allow FreeSWITCH to determine a gateway has failed ahead of time which allows the bridge to go to the secondary immediately rather than waiting for a timeout during call setup.

Call Camping

Call camping, or camp-on, allows setting the the incoming call to wait if the bridge destination is occupied. This behavior is controlled by a number of channel variables that need to be set up before calling bridge application:

VariableDescription
camponControls whether camping is enabled or not.
campon_announce_soundFile to play back after the first bridge fails (for example, to announce what key to press to skip to fallback extension)
campon_fallback_contextOptional context name where the call is transferred for fallback
campon_fallback_dialplanOptional dialplan name where the call is transferred for fallback
campon_fallback_extenExtention number where the call is transferred for fallback
campon_hold_musicOptional hold music to play during camp-on instead of default MOH
campon_retriesNumber of bridge re-tries before falling back. Default: 100
campon_sleepControls how long to wait (in seconds) before starting a retry. Default: 10
campon_stop_keyDTMF digit that breaks the campon loop and skips directly to fallback extension
campon_timeoutThis variable controls how long to attempt each bridge before timing out. It works exactly like call_timeout but only applies to camping. Default: 10

Usage:

 

Special channels

These special channels are specified where a normal endpoint would be specified, such as sofia, but provide customized treatment of a call.

error

You can bridge the call to the error channel in order to specify a hangup cause.

gateway

When dialing using the gateway channel, it will use the authentication details specified in the sip_profiles definition if challenged.

group

The group special channel will dynamically create a dial string to reach all endpoints defined as part of a group in the directory by using the 'group_call' function.

This is the same as:

loopback

Loopback creates a pseudo-endpoint that starts a new pass through the specified dialplan, but can cause unusable CDR entries as a result. Do not use unless there is no other option, but expect to spend time troubleshooting it.

This example searches the inherited dialplan for extension 1000 in the inherited context.

Icon

Loopback is evil and should only be used as a last resort, when no other approach is possible. - anthm

For more info look at Loopback endpoint

user

Since FreeSWITCH has a user directory, you can save how to reach every user in the user's directory entry by saving it in its "dial-string" parameter. When dialing using the user channel, it will lookup the dial-string stored in the extension's directory entry and dial it instead.

Icon

If the user has no dial-string, the default dial-string specified in the directory entry for the channel's domain is used instead.

If you want to route to many user channels, you will have to separate them by :_: as opposed to the comma "," to generate an originate command for each user.

Note again: You have to be careful with whitespace here generally. For some reason, FS will see user [bob@domain ] and NOT [bob@domain] which will make it not find the user, if you try to be fancy like for example this:

So be careful about formatting.

See Also

Loopback endpoint — a special user channel for very specialized purposes

Channel variables — dicsusses how channel variables, especially loopback_bowout, can be set and how they affect this command