Freeswitch: mod_dptools: bridge

Создает мост между новым и уже сущесвующим каналами.

Используется для вызова одной или нескольких endpoints.
Множество endpoints могут быть перечислены через запятую , или через pipe - |, для вызова одновременно или по очереди, соответственно.
Также для вызова нескольких endpoints, может быть использована группа вызовов.

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

Основные типы ''endpoints'' для ''bridge''

  • user/<user_id>@<domain>
    • user, это псевдоним (alias) для устройства зарегистрированного на этом сервере, в противоположность номеру вызываемому через транк (gateway), когда вызывается устройство зарегистрированное на другом сервере.
  • lcr/<number>
    • номер вызываемый через модуль lcr.
  • sofia/<profile_name>/<number>@<sip_uri>
    • пользователь вызываемый через sip profile.
  • sofia/gateway/<gateway_name>/<number>
    • номер вызываемые через транк (gateway).
  • loopback/<number>/XML/<dialplan_name>
    • Псевдо интерфейс, для вызова через контекст диалплана.
  • group(<group_name>)
    • Вызов группы номеров, назначенных через mod_db/group

Примеры выражений с API командами:

Простой вызов endpoint:

bridge <target_endpoint>

Вызов множества endpoints одновременно.
Без ограничений по кол-ву одновременных вызовов, первый ответивший выигрывает.

bridge <target_endpoint>[,<target_endpoint>]

Вызов нескольких endpoints по очереди.
Неограниченное кол-во отказов:

bridge <target_endpoint>[|<target_endpoint>]

Задать переменные для B-leg используя квадратные скобки [...]:

Область видимости переменных заданных в квадратных скобках, распространяется только на канал перед которым они указаны.
bridge [variable_scope=endpoint-1]<target_endpoint>,[variable_scope=endpoint-2]<target_endpoint>

Задать переменные для B-leg используя фигурные скобки {...}:

Область видимости переменных заданных в фигурных скобках распространяется на каждый из перечисленных каналов.
Под каждым, на приведенном ниже примере, понимается, что переменная variable_scope в фигурных скобках, назначается target_endpoint1,target_endpoint2 и target_endpoint3,
а переменные заданные в квадратных скобках, назначаются только каналам, перед которыми они указаны.
Если одна и та же переменная задана и в фигурных и в квадратных скобках, квадратные переназначают её.
См. также: channel_variables_in_dial_strings
bridge {variable_scope=thread_global}[variable_scope=endpoint-1]<target_endpoint1>[,[variable_scope=endpoint-2]<target_endpoint2>][|[variable_scope=endpoint-3]<target_endpoint3>]

Установить переменные на B-leg для множества потоков используя угловые скобки <...>.

Enterprise Originate

ВАЖНО, вы должны установить continue_on_fail=true на A-leg вызова!

Так называемый 'enteprise originate' синтаксис, это способ одновременной оригинации множества вызовов, каждый в отдельном потоке (threads).
При обычном одновременном вызове множества endpoints при помощи , в качестве разделителя, это происходит в одном потоке.
Для использования многопоточного вызова просто укажите в качестве разделителя :_:.
Каждый вызываемый канал может иметь собственные блоки переменных заключенные в {} и [] скобки.
Чтобы добавить переменные для всех enterprise originate каналов сразу, используйте угловые скобки - <>:

originate <all_threads=true>{first_thread=true}sofia/gw/foo/bar:_:{second_thread=true}sofia/gw/foo/baz

Это может быть полезно при переадресации вызовов. Без этого Freeswitch сбросит одновременные вызовы, если обнаружит переадресацию в одном из каналов, другие перестанут вызываться.
По умолчанию каждый новый поток будет иметь собственную A-leg запись в CDR. Чтобы соотнести эти потоки друг с другом можно использовать переменную ent_originate_aleg_uuid.

bridge <variable_scope=super-global>{variable_scope=thread1}[variable_scope=leg1a]<target_endpoint>[,[variable_scope=leg1b]<target_endpoint>][|<target_endpoint>]:_:{variable_scope=thread2}[variable_scope=leg2a]<target_endpoint>[,[variable_scope=leg2b]<target_endpoint>][|<target_endpoint>]

2.1 Dialplan Examples

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

<action application="bridge" data="sofia/internal/9998881111@sip.yourprovider.com"/>

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.

\\  <action application="bridge" data="sofia/internal/100%${sip_profile},sofia/internal/101%${sip_profile}"/>\\ 

To dial multiple contacts all at once:

\\  <action application="bridge" data="sofia/internal/1010@sip.yourprovider.com,sofia/sip/1011@sip.yourprovider.com"/>\\ 

To dial multiple contacts one at a time:

\\  <action application="bridge" data="sofia/internal/1010@sip.yourprovider.com|sofia/sip/1011@sip.yourprovider.com"/>\\ 

Вызвать внешний SIP адрес, требующий аутентификацию, на лету, без создания транков (gateways).

  <action application="bridge" data="{sip_auth_username=foo,sip_auth_password=bar}sofia/internal/9998881111@sip.yourprovider.com"/>

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

\\  <action application="bridge" data="sip:12135551212;rn=12135550000;npdi=yes@1.2.3.4:5060>\\ 

or

\\  <action application="export" data="nolocal:sip_invite_tel_params=rn=12135550000;npdi=yes"/>\\  <action application="export" data="nolocal:sip_invite_params=user=phone"/>\\ 

or

\\  <action application="bridge" data="{sip_invite_tel_params=rn=12135550000;npdi=yes,sip_invite_params=user=phone}sofia/gateway/gateway_name/12135551212"/>\\ 

will result in:

\\  INVITE sip:12135551212;rn=12135550000;npdi=yes@1.2.3.4;user=phone SIP/2.0\\ 

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:

\\  <action application="bridge" data="sip:12135551212;rn=12135550000;npdi=yes@1.2.3.4:5060^12135551212">\\ 

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:

3.1 Timeout

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

\\   <action application="set" data="call_timeout=20"/>\\ 

3.2 No Media Mode

See full discussion at Bypass Media Overview.

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

\\  <action application="set" data="bypass_media=true"/>\\ 

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

\\  originate {bypass_media=true}sofia/default/1000@host1 &bridge(sofia/default/1001@host2)\\ 

3.3.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.

\\  <action application="set" data="effective_caller_id_name=John Freeswitch"/>\\  <action application="set" data="effective_caller_id_number=1234567"/>\\ 

3.4 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.

\\   <action application="set" data="ringback=${us-ring}"/>\\ 

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

3.5 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:

\\  <action application="bridge" data="[origination_caller_id_number=1234]sofia/<profile>/<extension>,[origination_caller_id_number=55555]sofia/<profile>/<extension>"/>\\ 

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:

\\   <action application="set" data="ignore_early_media=true" />\\ 

3.6 Implementing Failover

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

\\   <action application="bridge" data="sofia/gateway/primary/dialstring|sofia/gateway/secondary/dialstring"/>\\ 

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.

3.7 Call Camping

See Call Camping|

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

4.1 error

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

\\ <action application="bridge" data="error/user_busy" />\\ 

4.2 gateway

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

\\ <action application="bridge" data="sofia/gateway/mygatewayname/555123456" />\\ 

4.3 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.

\\ <action application="bridge" data="group/support@${domain_name}"/>\\ 

This is the same as:

\\ <action application="bridge" data="${group_call(support@${domain_name})}"/>\\ 

4.4 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.

\\ <action application="bridge" data="loopback/1000" />\\ 

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

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

4.5 user

[ Note: This section was imported directly from the old wiki and must be edited to the rest of the text under «user» to remove redundancies. ]

If the dial-string param is set for a user or a domain you can bridge a call to the user endpoint without going through a profile. The default dial-string param in the example config files for FreeSWITCH has the following syntax:

\\ <param name="dial-string" value="{presence_id=${dialed_user}@${dialed_domain},transfer_fallback_extension=${dialed_user}}${sofia_contact(${dialed_domain}/${dialed_user}@${dialed_domain})}"/>\\ 



When this param is set on the destination user you can bridge to it this way:

\\ <action application="bridge" data="user/username@domain"/>\\ 




When you use the user channel the user is pulled from your domain in your directory then the main domain is searched for a <params> tag. If that is not found it searches in the <user> for a <params> tag. If a <params> tag is located, it looks for the param «dial-string» as the originate string to use for that user. The special variables ${dialed_user} and ${dialed_domain} are available in this string for expansion based on the user and domain specified.

for instance if all calls are sip you could set the dial-string in your whole domain as

\\ <params>\\   <param name="dial-string" value="${sofia_contact(${dialed_user}@${dialed_domain})}"/>\\ </params>\\ 



Be aware that the user channel should not be used along with forked dialing. Instead use the following in your data= for the bridge:

\\ data="${sofia_contact(user/username@domain)},sofia/gateway/provider/somenum\\ 


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.

\\ # specifying this in the dialplan\\ <action application="bridge" data="user/bob@domain" />\\ # would be translated into\\ <action application="bridge" data="sofia/sip/100%${sip_profile},sofia/sip/101%${sip_profile}"/>\\ 


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.

\\    <action application="bridge" data="user/bob@domain:_:user/alice@domain"/>\\ 

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:

\\    <action application="bridge" data="\\      user/bob@domain :_:\\      user/alice@domain\\   "/>\\ # The above XML is broken! FreeSWITCH will complain about unknown users:\\ # [bob@domain ] and [alice@domain       ]\\ 

So be careful about formatting.

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


 

  • freeswitch/mod/mod_dptools/bridge.txt
  • Последние изменения: 2020/09/18