CommuniGate Pro: PSTN

The CommuniGate Pro Router processes every Signal address in the system.

The Router uses Default or Custom records to detect telephony (PSTN) type addresses and to convert them to the standard E.164 form (+country_code area_code local_number) in the fictitious telnum domain name. For example, when a SIP phone user dials 011 44 3335555, the Server receives that address as sip:011443335555@client1.dom URI, and the Router converts this address into +44333555@telnum address.
Usually all numeric addresses of the certain length are processed as PSTN numbers.
See the Router section to learn about the Router records used to detect telephony type addresses.
The Router maps PSTN numbers to local or remove VoIP addresses, if possible.
The Router checks if an address (number) in the fictitious telnum domain is assigned to some local Account. If an Account is found, the Router routes the address to that Account.
For addresses not assigned to any local Account, the Router can use global and local ENUM services, as well as CommuniGate Pro Forwarders.
The Router directs unmapped PSTN numbers either directly to a PSTN Gateway, or to a CommuniGate Pro Real-Time application designed to support external PSTN Gateways.

The Router can route calls to the PSTN network via a Real-Time Application.
The CommuniGate Pro Server comes with a "stock" gatewaycaller application that can be used for relaying outgoing PSTN calls to one or several PSTN gateways. This section describes this application functionality.

When the gatewayCaller application receives an incoming call, it requires authentication. As a result, only the users with the Accounts on your CommuniGate Pro Server or Cluster can place calls via this application.

When an authenticated call request is received, the application retrieves and uses the following Account PSTN Settings:

PSTNGatewayName (Gateway Name): The Gateway domain name. It is used as an address to send the call requests to.
If this setting value is empty, the Account is not allowed to make PSTN calls and its calls are rejected.
PSTNGatewayVia (Gateway Address): This setting is a non-empty string if the requests to the Gateway should not be sent directly (to the DNS-resolved addresses), but they should be sent via a different proxy. This setting should contain the domain name or the IP address of that proxy.
PSTNFromName (Caller ID): This setting specifies the address (usually, a PSTN number) to be used as the Caller ID (the From: address) in the call request sent to the Gateway. If this setting value is empty, the From: address of the original request is used.
PSTNGatewayAuthName (Name for Gateway) PSTNGatewayPassword (Password for Gateway): If the Gateway requires authentication, these settings specify the authentication data to use with the requests sent to the Gateway.
PSTNBillingPlan (Billing Plan): The "stock" gatewaycaller application does not use this setting.

A CommuniGate Pro Account can use a default value for each of its setting (taken either from the Domain-wide or Server-wide/Cluster-wide Default Settings) or a setting value can set explicitly for that Account. As a result, all Accounts in all Domains can use the same Gateway and same Gateway credentials, but different Caller ID settings, or each Domain and/or each Account can use its own Gateway, with Domain or Account-specific credentials.

The application needs to retrieve Settings from other Accounts, so it should be started on behalf of an Account with the Domain Administrator access rights.
The automatically created postmaster or pbx Accounts can be used.

The application expects to get the destination number as its parameter.
The following Router record routes all addresses in the fictitious pstn domain to the gatewaycaller application started on behalf of the pbx Account in the Main Domain, and it passes the "user part" of the pstn domain address as the application parameter:

<*@pstn> = gatewaycaller{*}#pbx

After processing all Account Settings, the application starts a new Task and instructs that Task to send a call request to the selected Gateway using the retrieved Account settings. If the call succeeds, the original and new Tasks "bridge" the media streams.
The original Task processes Signal requests from the caller, the second Task processes the requests from the Gateway. Some of these requests are processed with the Tasks themselves, some are relayed to the peering Task for relaying to the caller or to the gateway.

The technology used to implement this type of call setup (when a call is established using two formally independent Signaling sessions) is called a Back-to-Back User Agent (B2BUA).

When a caller wants to Transfer a call, the Transfer request is sent to the original Task. This Task implements the requested call transfer itself, switching to some other VoIP device/entity. The second Task does not send any Transfer request to the Gateway, but it may send a call update (SIP re-INVITE or UPDATE) request to the gateway in order to redirect its media streams to the new call participant.

Some PSTN Gateways do not support even the simple call update requests. Specify the name of those Gateways with a leading asterisk (*) symbol. The application will remove that symbol from the name, and it will not bridge media streams. The application will use a CommuniGate Pro Media Server channel to relay media between the caller and gateway. If the caller switches its media address by sending a call Update request, or if the caller sends a call Transfer request, the Media Server channel updates its internal information, and no request is sent to the Gateway, which continues to exchange media data with the Media Server channel.

If you need to use several different gateways per user or per domain (depending on the destination), you can specify the gateaycaller PSTNxxxxxx settings as dictionaries. For example:

PSTNGatewayName:{gw1=provider1.com;gw2=provder2.com;}
PSTNFromName:{gw1=fromName1;gw2=fromName2;}

You can Route different PSTN numbers to different gateways by passing the second parameter to the gatewaycaller application:

<+46(5-12d)@pstn> = gatewaycaller{+46*,gw1}#pbx
<*@pstn> = gatewaycaller{*,gw2}#pbx

All calls to unprocessed numbers in the pstn domain will be routed to the gatewaycaller application, and this application will get the second parameter of "gw1" if the callee is in Sweden (a E.164 number starting with +46), and "gw2" in all other cases.
The gatewaycaller application reads all required PSTNxxxxxx settings. If a settings value is a dictionary, it takes either the "gw1" or the "gw2" element from the dictionary.

Local Area Calls

When a user dials a "short" number (a number without the country code and the area code), the call is expected to be delivered to the that number with the user's own area code.

A Router record created during a CommuniGate Pro Server installation routes all calls to 7 digit number address in any local Domain to the localAreaCall application.

The stock localAreaCall application requires the caller to authenticate, and then it retrieves the following Account PSTN Settings:

PSTNAreaCode (Local Area Code): This setting specifies the Account country code and the local area code.

The applications needs to retrieve Settings from other Accounts, so it should be started on behalf of an Account with the Domain Administrator access rights.
The automatically created postmaster or pbx Accounts can be used.

The application expects to get the dialed destination number as its parameter.
The following Router record routes all 7-digit addresses in all local Domains to the localAreaCall application started on behalf of the pbx Account in the Main Domain, and it passes that address (a 7-digit number) as the application parameter:

<(7d)@*> = localAreaCall{*}#pbx@localhost

The application retrieves the callers country code and the local area code from the caller's PSTNAreaCode Account Settings, removes all non-digit symbols from the Setting value, catenates the "cleaned" with the dialed number and the @telnum domain name, and Redirects the call request to the resulting address.

The Signal module processes the redirected request using the Router, so it can be directed to a PSTN Gateway or (after successful mapping) directly to some VoIP address.

Domestic Calls

Many countries traditionally use separate calling prefixes for out-of-area domestic and international calls. Many countries use 0area_code local_number numbers for domestic calls, while 00country_code area_code local_number numbers are used for international calls.

If all CommuniGate Pro users are located in the same country, domestic calls can be properly routed with a single Router Record. For example, if all CommuniGate Pro users are located in Germany (country code 49, 0 is the out-of-area prefix), the following Router record can be used (note the order of these records):

<0(7-20d)@*> = +49*@telnum
<00(8-20d)@*> = +*@telnum

You can also use the localAreaCall application to properly route Domestic calls. Route all calls with the domestic prefix to the localAreaCall application, but specify the second parameter - a string c:

<0(8-20d)@*> = localAreaCall{*,c}#pbx@localhost

The localAreaCall application does the same processing as it does for the Local Area calls. But instead of using the entire PSTNAreaCode Setting value, it uses only:

the country code if the setting value is specified as country_code-area_code or as country_code(area_code) or
the first digit if this digit is 1 (North America) or 7 (Russia) or
the first 2 digits

Emergency Calls

Call to Emergency Response Centers are done by dialing a well-known number, such as 911 in North America or 112 in Western Europe.

Use the Router to redirect calls to these numbers (in any Domain) to the emergency application:

<911@*> = emergency#pbx@localhost

The stock emergency application requires the caller to authenticate, and then it retrieves the following Account PSTN Settings:

PSTNEmergency (Emergency Code): This setting specifies the way to contact the Emergency Response Center for this Account user.

The application processes the retrieved PSTNEmergency setting value:

If the retrieved string has the call= prefix, then the remaining part of the string is used as the address to redirect the call to.
If the retrieved string has the http= prefix, then application reads the emergency.settings from the Real-Time Environment. This file should contain a dictionary.
The application makes an HTTP request using the emergency.settings dictionary as parameters for the HTTPCall CG/PL operation. The call body is a dictionary with the following elements:

userName

the authenticated caller's Account Name (accountName@domainName).

fromWhom

the caller's name (URI) as specified in the Request From: data.

areaCode

the PSTNEmergency Setting value with the http= prefix removed.

When the application receives an HTTP response, the HTTP response body should contain a string or an array with the destination address(es).

The application redirects the call to the specified address(es).

Incoming Calls

PSTN Gateways can direct incoming calls to the CommuniGate Pro Server. There incoming Gateways usually have almost the same problems as the outoging Gateways: inability to transfer calls, inability to switch media streams, etc.

If incoming calls are routed to the CommuniGate Pro PBX application, that application acts as a B2BUA and addresses these issues.

If incoming calls are directed to individual CommuniGate Pro Accounts (or other Objects), a direct session between the Gateway and the end-user device can be established, and all Gateway problems will be exposed to the end-user.

To solve PSTN Gateway problems when directing calls to addresses that are not necessarily answered with CommuniGate Pro Real-Time Applications, you may want to route all these calls to a special gatewayincoming application. This application, acting as B2BUA, will create a separate Task ("call leg") to call the destination and it will bridge the call in the same way the gatewaycaller application processes outgoing calls.

The stock gatewayincoming application expects the destination address to be delivered to it as an application parameter. If the Gateway sends incoming requests to your system using addresses in a special domain incoming.company.dom, then the following Router record will direct them to the gatewayincoming application:

<*@incoming.company.dom> = gatewayincoming{*}#pbx@localhost

If you know that the Gateway addresses all your local Accounts as Domestic numbers (numbers without the country code), you can correct his in the Router record. For example if the Gateway uses 10-digit North American numbers without the 1 country code, you can use the following Router record:

<*@incoming.company.dom> = gatewayincoming{1*}#pbx@localhost

PSTN

Call Routing

Outgoing Calls via B2BUA

Local Area Calls

Domestic Calls

Emergency Calls

Incoming Calls

PSTN Account Settings