PSTN

PSTN Gateways can direct incoming PSTN calls to a SIP entity, such as a CommuniGate Pro Server. These incoming Gateways usually are unable to transfer calls, to switch media streams, etc.

To overcome PSTN Gateway limitations, incoming calls from those gateways are usually directed to a CommuniGate Pro Real-Time applications acting as a B2BUA.
There is a stock gatewayincoming application designed to be used for this purpose.

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:

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 PSTN calls are often directed not to a particular user, but to a Real-Time application acting as a "PBX center". This application answers incoming calls, and allows the callers to select the user to call, call the selected Account, and bridges the call. Since this application also acts as a B2BUA, PSTN Gateway calls can be routed to it directly, without first routing them to the special B2BUA application such as the gatewayincoming application:

Some PSTN Gateways cannot be configured to direct incoming calls to a specific address (such as a CommuniGate Pro Account). Instead, these Gateways expect SIP REGISTER requests to be sent to them periodically.
These SIP requests specify the Gateway target account (usually - a PSTN phone number), the credentials (such as some username and password), and the SIP address to direct incoming PSTN calls to.

Each CommuniGate Pro Account can contain zero, one, or several RSIP records. Each RSIP record specifies an account information for some remote PSTN Gateway. The CommuniGate Pro server periodically sends the SIP REGISTER requests to that gateway using the specified information, and then the PSTN Gateway receives a phone call, it directs it to this CommuniGate Pro Account.

A Server or a Domain Administrator with the RSIP Registrations Access Right can manage the Account RSIP Registration records.
Open the WebAdmin Account Management pages, then open the RSIP page in the Real-Time section:

Each RSIP record should have a unique name, used solely for its identification with the Account.

To create a new RSIP record, select some name for it and enter it into the Name field in the last table row. Fill other fields and press the Update button.

To modify an RSIP record, modify values in the record fields and press the Update button.

To remove an RSIP record, set its Period value to Never and press the Update button.

Register Every

This setting specifies how often the Server should send the SIP REGISTER requests. These requests use the SIP registration expiration time which is 2 minutes longer than this time period.
Use the value the PSTN Gateway provider recommends.

Account

This setting specifies the Account name (the address) for the REGISTER requests. If the specified value does not contain the @ symbol, the at Host value is appended to it then the REGISTER request is sent.
Use the value assigned to you by the PSTN Gateway provider (usually - the phone number).

at Host

This setting specifies the domain name or the IP Network Address of the PSTN Gateway. The SIP Register requests are sent to that address.
Use the value recommended by the PSTN Gateway provider.
If the REGISTER request should be sent via some SIP proxy, specify that proxy domain name or the IP Network Address after the PSTN Gateway name, separated with the @ symbol: gatewayName@proxyName

Authentication Name, Password

These settings specify the credentials (the user name and the password) needed to authenticate the SIP Register request sender.
Note: the Authentication name may or may not contain the @ symbol followed by some domain name.
If the Authentication Name setting is left empty, the Account setting value is used.
Use the values assigned to you by the PSTN Gateway provider.

Target

This setting specifies the Account address the PSTN Gateway should send the incoming calls to. Usually this field is left empty, in this case the calls are directed to this Account.

The last field contains the time when the last SIP REGISTER request completed, and, optionally, an error code received from the PSTN Gateway.

The RSIP Registration functionality is implemented using the Chronos component. At the scheduled time, the component starts the rsipRegister Real-Time Application, which performs the REGISTER transaction.

The SIP REGISTER request Contact field is composed so that incoming calls from the PSTN Gateway are sent to the gatewayincoming application which acts as a B2BUA and bridges the call to this Account (or to the Account specified with the Target field).
If you want to send the incoming calls directly to this Account, bypassing the B2BUA, add the asterisk (*) symbol in front of the At Host setting value.

When the CommuniGate Pro Server is installed, it creates the pbx Account in the Main Domain. A Signal Rule is automatically created for this Account to direct all incoming calls to the PBX Center application.
If you want to specify SIP Registration records for this pbx Account, so it will receive incoming calls from the sip.provider.dom PSTN Gateway, specify the At Host setting as *sip.provider.dom.

Account users can review their RSIP Registration records and (if the RSIP Registration setting is enabled) modify them using the WebUser Interface.

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 remote 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)

This setting contains the name of the billing plan to apply. The stock gatewaycaller application tries to read the specification for the billing plan standard from the PBX environment file with the name billingplan-standard.objdata. The file should contain a dictionary where each key is a phone number prefix and the value is either a number with the call cost per a minute, or a reason string to use to block calls to numbers with this prefix:

{
  1990 = blocked; // calls to +1-990-XXX-XXXX are blocked
  1 = #0;         // calls to North American numbers are free
  "" = #10;       // everything else costs 10 units per minute
}

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:

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 hash (#) 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 gatewaycaller PSTNxxxxxx settings as dictionaries. For example:

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

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.

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:

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.

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

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:

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

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:

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

PSTN Settings are implemented as Custom Account Settings. The main WebAdmin Account Management page does not show the Custom Settings with names starting with the PSTN prefix. Instead, a link to a special PSTN Settings page is available on the Account Settings and Account Default Settings pages.

Click the PSTN link to open the PSTN Settings page:

A Domain Administrator should have the PSTN Settings Access Right to modify PSTN Settings.