6. Features

6.1. Managing System Administrators
6.1.1. Configuring Administrators
6.1.2. Access Rights of Administrators
6.2. Access Control for SIP Calls
6.2.1. Block Lists
6.2.2. NCOS Levels
6.2.3. IP Address Restriction
6.3. Call Forwarding and Call Hunting
6.3.1. Setting a simple Call Forward
6.3.2. Advanced Call Hunting
6.4. Local Number Porting
6.4.1. Local LNP Database
6.4.2. External LNP via LNP API
6.5. Emergency Mapping
6.5.1. Emergency Mapping Description
6.5.2. Emergency Mapping Configuration
6.6. Header Manipulation
6.6.1. Header Filtering
6.6.2. Codec Filtering
6.6.3. Enable History and Diversion Headers
6.7. SIP Trunking with SIPconnect
6.7.1. User provisioning
6.7.2. Inbound calls routing
6.7.3. Number manipulations
6.7.4. Registration
6.8. Trusted Subscribers
6.9. Peer Probing
6.9.1. Introduction to Peer Probing Feature
6.9.2. Configuration of Peer Probing
6.9.3. Monitoring of Peer Probing
6.9.4. Further Details for Advanced Users
6.10. Fax Server
6.10.1. Fax2Mail Architecture
6.10.2. Sendfax and Mail2Fax Architecture
6.11. Voicemail System
6.11.1. Accessing the IVR Menu
6.11.2. IVR Menu Structure
6.11.3. Type Of Messages
6.11.4. Folders
6.11.5. Voicemail Languages Configuration
6.11.6. Flowcharts with Voice Prompts
6.12. Configuring Subscriber IVR Language
6.13. Sound Sets
6.13.1. Configuring Early Reject Sound Sets
6.14. Conference System
6.14.1. Configuring Call Forward to Conference
6.14.2. Configuring Conference Sound Sets
6.14.3. Joining the Conference
6.14.4. Conference Flowchart with Voice Prompts
6.15. Malicious Call Identification (MCID)
6.15.1. Setup
6.15.2. Usage
6.15.3. Advanced configuration
6.16. Subscriber Profiles
6.16.1. Subscriber Profile Sets
6.17. SIP Loop Detection
6.18. Call-Through Application
6.18.1. Administrative Configuration
6.18.2. Call Flow
6.19. Calling Card Application
6.19.1. Administrative Configuration
6.19.2. Call Flow
6.20. Invoices and Invoice Templates
6.20.1. Invoices Management
6.20.2. Invoice Templates
6.20.3. Invoices Generation
6.21. Email Reports and Notifications
6.21.1. Email events
6.21.2. Initial template values and template variables
6.21.3. Password reset email template
6.21.4. New subscriber notification email template
6.21.5. Invoice email template
6.21.6. Email templates management
6.22. The Vertical Service Code Interface
6.22.1. Vertical Service Codes for PBX customers
6.22.2. Configuration of Vertical Service Codes
6.22.3. Voice Prompts for Vertical Service Code Configuration
6.23. Handling WebRTC Clients
6.24. XMPP and Instant Messaging
6.25. Call Recording
6.25.1. Introduction to Call Recording Function
6.25.2. Information on Files and Directories
6.25.3. Configuration
6.25.4. REST API
6.26. SMS (Short Message Service) on Sipwise NGCP
6.26.1. Configuration
6.26.2. Monitoring, troubleshooting
6.26.3. REST API

The sip:provider PRO provides plenty of subscriber features to offer compelling VoIP services to end customers, and also to cover as many deployment scenarios as possible. In this chapter, we provide the features overview and describe their function and use cases.

6.1. Managing System Administrators

The sip:provider PRO offers the platform operator with an easy to use interface to manage users with administrative privileges. Such users are representatives of resellers, and are entitled to manage configuration of services for Customers, Subscribers, Domains, Billing Profiles and other entities on Sipwise NGCP.

Administrators, as user accounts, are also used for client authentication on the REST API of NGCP.

There is a single administrator, whose account is enabled by default and who belongs to the default reseller. This user is the superuser of the NGCP administrative web interface (the so-called "admin panel"), and he has the right to modify administrators of other Resellers as well.

6.1.1. Configuring Administrators

Configuration of access rights of system administrators is possible through the admin panel of NGCP. In order to do that, please navigate to Settings → Administrators.

List of System Administrators

Figure 26. List of System Administrators


You have 2 options:

  • If you’d like to create a new administrator user press Create Administrator button.
  • If you’d like to update an existing administrator user press Edit button in its row.

There are some generic attributes that have to be set for each administrator:

Generic System Administrator Attributes

Figure 27. Generic System Administrator Attributes


  • Reseller: each administrator user must belong to a Reseller. There is always a default reseller (ID: 1, Name: default), but the administrator has to be assigned to his real reseller, if such an entity (other than default) exists.
  • Login: the login name of the administrator user
  • Password: the password of the administrator user for logging in the admin panel, or for authentication on REST API

The second set of attributes is a list of access rights that are discussed in subsequent section of the handbook.

6.1.2. Access Rights of Administrators

The various access rights of administrators are shown in the figure and summarized in the table below.

Access Rights of System Administrators

Figure 28. Access Rights of System Administrators


Table 1. Access Rights of System Administrators

Label in admin list

Access Right

Description

not shown

Is superuser

The user is allowed to modify data on Reseller level and — among others — is able to modify administrators of other resellers. There should be only 1 user on Sipwise NGCP with this privilege.

Master

Is master

The user is allowed to create, delete or modify other Admins who belong to the same Reseller.

Active

Is active

The user account is active, i.e. the admin user can login on the web panel or authenticate himself on REST API; otherwise user authentication will fail.

Read Only

Read only

The user will only be able to list various data but is not allowed to modify anything.

  • For the web interface this means that Create… and Edit buttons will be hidden or disabled.
  • For the REST API this means that only GET, HEAD, OPTIONS HTTP request methods are accepted, and NGCP will reject those targeting data modification: PUT, PATCH, POST, DELETE.

Show Passwords

Show passwords

The user sees subscriber passwords (in plain text) on the web interface.

info

Admin panel user passwords are stored in an unreadable way (cryptographic hash digest) in the database, while subscriber passwords are basically always stored in plain text. The latter happens on purpose, e.g. to make subscriber data migration possible.

Show CDRs

Call data

This privilege has effect on 2 items that will be displayed on admin panel of NGCP, when Subscriber → Details is selected:

  1. PBX Groups list
  2. Captured Dialogs list

Show Billing Info

Billing data

Some REST API resources that are related to billing are disabled: HTTP requests on /api/vouchers, /api/topupcash and /api/topupvoucher resources are rejected.

Lawful Intercept

Lawful intercept

If the privilege is selected then the REST API for interceptions (that is: /api/interceptions) is enabled; if the privilege is not selected then the interceptions API is disabled.

info

This means that besides enabling LI in config.yml configuration file one also needs to enable the API via the LI privilege of an administrator user, so that NGCP can really provide LI service.


6.2. Access Control for SIP Calls

There are two different methods to provide fine-grained call admission control to both subscribers and admins. One is Block Lists, where you can define which numbers or patterns can be called from a subscriber to the outbound direction and which numbers or patterns are allowed to call a subscriber in the inbound direction. The other is NCOS Levels, where the admin predefines rules for outbound calls, which are grouped in certain levels. The subscriber can then just choose the level, or the admin can restrict a subscriber to a certain level. Also sip:provider PRO offers some options to restrict the IP addresses that subscriber is allowed to use the service from. The following sections describe these features in detail.

6.2.1. Block Lists

Block Lists provide a way to control which users/numbers can call or be called, based on a subscriber level, and can be found in the Call Blockings section of the subscriber preferences.

Subscriber Block Lists

Block Lists are separated into Administrative Block Lists (adm_block_*) and Subscriber Block Lists (block_*). They both have the same behaviour, but Administrative Block Lists take higher precedence. Administrative Block Lists are only accessible by the system administrator and can thus be used to override any Subscriber Block Lists, e.g. to block certain destinations. The following break-down of the various block features apply to both types of lists.

6.2.1.1. Block Modes

Block lists can either be whitelists or blacklists and are controlled by the User Preferences block_in_mode, block_out_mode and their administrative counterparts.

  • The blacklist mode (option is not checked tells the system to allow anything except the entries in the list. Use this mode if you just want to block certain numbers and allow all the rest.
  • The whitelist mode indicates to reject anything except the entries in the list. Use this mode if you want to enforce a strict policy and allow only selected destinations or sources.

You can change a list mode from one to the other at any time.

6.2.1.2. Block Lists

The list contents are controlled by the User Preferences block_in_list, block_out_list and their administrative counterparts. Click on the Edit button in the Preferences view to define the list entries.

In block list entries, you can provide shell patterns like * and []. The behavior of the list is controlled by the block_xxx_mode feature (so they are either allowed or rejected). In our example above we have block_out_mode set to blacklist, so all calls to US numbers and to the Austrian number +431234567 are going to be rejected.

Outgoing Block List

Click the Close icon once you’re done editing your list.

6.2.1.3. Block Anonymous Numbers

For incoming call, the User Preference block_in_clir and adm_block_in_clir controls whether or not to reject incoming calls with number supression (either "[Aa]nonymous" in the display- or user-part of the From-URI or a header Privacy: id is set). This flag is independent from the Block Mode.

6.2.2. NCOS Levels

NCOS Levels provide predefined lists of allowed or denied destinations for outbound calls of local subscribers. Compared to Block Lists, they are much easier to manage, because they are defined on a global scope, and the individual levels can then be assigned to each subscriber. Again there is the distinction for user- and administrative-levels.

If case of a conflict, when the Block Lists feature allows a number and NCOS Levels rejects the same number or vice versa, the number will be rejected.

NCOS levels can either be whitelists or blacklists.

  • The blacklist mode indicates to allow everything except the entries in this level. This mode is used if you want to just block certain destinations and allow all the rest.
  • The whitelist mode indicates to reject anything except the entries in this level. This is used if you want to enforce a strict policy and allow only selected destinations.
6.2.2.1. Creating NCOS Levels

To create an NCOS Level, go to SettingsNCOS Levels and press the Create NCOS Level button.

NCOS Levels

Select a reseller, enter a name, select the mode and add a description, then click the Save button.

Create NCOS Levels

6.2.2.2. Creating Rules per NCOS Level

To define the rules within the newly created NCOS Level, click on the Patterns button of the level.

Enter NCOS Pattern View

There are 2 groups of patterns where you can define matching rules for the selected NCOS Level:

  • NCOS Number Patterns: here you can define number patterns that will be matched against the called number and allowed or blocked, depending on whitelist / blacklist mode. The patterns are regular expressions.
  • NCOS LNP Carriers: here you can select predefined LNP Carriers that will be allowed (whitelist mode) or prohibited (blacklist mode) to route calls to them. (See Section 6.4.1, “Local LNP Database” in the handbook for the description of LNP functionality)
NCOS Patterns List

Figure 29. NCOS Patterns List


In the NCOS Number Patterns view you can create multiple patterns to define your level, one after the other. Click on the Create Pattern Entry Button on top and fill out the form.

Create NCOS Number Pattern

Figure 30. Create NCOS Number Pattern


In this example, we block (since the mode of the level is blacklist) all numbers starting with 439. Click the Save button to save the entry in the level.

There are 2 options that help you to easily define specific number ranges that will be allowed or blocked, depending on whitelist / blacklist mode:

  • Include local area code: all subscribers within the caller’s local area, e.g. if a subscriber has country-code 43 and area-code 1, then selecting this checkbox would result in the implicit number pattern: ^431.
  • Intra PBX calls within same customer: all subscribers that belong to the same PBX customer as the caller himself.

In the NCOS LNP Carriers view you can select specific LNP Carriers — i.e. carriers that host the called ported numbers — that will be allowed or blocked for routing calls to them (whitelist / blacklist mode, respectively).

Sipwise NGCP performs number matching always with the dialed number and not with the number generated after LNP lookup that is: either the original dialed number prefixed with an LNP carrier code, or the routing number.

An example of NCOS LNP Carrier pattern definition:

Create NCOS LNP Carrier

Figure 31. Create NCOS LNP Carrier


In the above example we created a rule that blocks calls to "LNP_Carr1" carrier, supposing we use blacklist mode of the NCOS Level.

info

Currently NGCP does not support filtering of individual phone numbers in addition to LNP Carrier matching. In other words: combining phone number and LNP Carrier patterns is not possible.

tip

There might be situations when phone number patterns may not be strictly aligned with telephony providers, for instance in case of full number portability in a country. In such cases using NCOS LNP Carriers patterns still allows for defining NCOS levels that allow / block calls to mobile numbers, for example. In order to achieve this goal you have to list all LNP carriers in the NCOS patterns that are known to host mobile numbers.

6.2.2.3. Assigning NCOS Levels to Subscribers/Domains

Once you’ve defined your NCOS Levels, you can assign them to local subscribers. To do so, navigate to SettingsSubscribers, search for the subscriber you want to edit, press the Details button and go to the Preferences View. There, press the Edit button on either the ncos or adm_ncos setting in the Call Blockings section.

Assign NCOS Level

You can assign the NCOS level to all subscribers within a particular domain. To do so, navigate to SettingsDomains, select the domain you want to edit and click Preferences. There, press the Edit button on either ncos or admin_ncos in the Call Blockings section.

Note: if both domain and subscriber have same NCOS preference set (either ncos or adm_ncos, or both) the subscriber’s preference is used. This is done so that you can override the domain-global setting on the subscriber level.

6.2.2.4. Assigning NCOS Level for Forwarded Calls to Subscribers/Domains

In some countries there are regulatory requirements that prohibit subscribers from forwarding their numbers to special numbers like emergency, police etc. While the sip:provider PRO does not deny provisioning Call Forward to these numbers, the administrator can prevent the incoming calls from being actually forwarded to numbers defined in the NCOS list: just select the appropriate NCOS level in the domain’s or subscriber’s preference adm_cf_ncos. This NCOS will apply only to the Call Forward from the subscribers and not to the normal outgoing calls from them.

6.2.3. IP Address Restriction

The sip:provider PRO provides subscriber preference allowed_ips to restrict the IP addresses that subscriber is allowed to use the service from. If the REGISTER or INVITE request comes from an IP address that is not in the allowed list, the sip:provider PRO will reject it with a 403 message. Also a voice message can be played when the call attempt is rejected (if configured).

By default, allowed_ips is an empty list which means that subscriber is not restricted. If you want to configure a restriction, navigate to SettingsSubscribers, search for the subscriber you want to edit, press Details and then Preferences and press Edit for the allowed_ips preference in the Access Restrictions section.

Edit Subscriber Allowed IP Addresses

Press the Edit button to the right of empty drop-down list.

You can enter multiple allowed IP addresses or IP address ranges one after another. Click the Add button to save each entry in the list. Click the Delete button if you want to remove some entry.

6.3. Call Forwarding and Call Hunting

The sip:provider PRO provides the capabilities for normal call forwarding (deflecting a call for a local subscriber to another party immediately or based on events like the called party being busy or doesn’t answer the phone for a certain number of seconds) and serial call hunting (sequentially executing a group of deflection targets until one of them succeeds). Targets can be stacked, which means if a target is also a local subscriber, it can have another call forward or hunt group which is executed accordingly.

Call Forwards and Call Hunting Groups can either be executed unconditionally or based on a Time Set Definition, so you can define deflections based on time period definitions (e.g. Monday to Friday 8am to 4pm etc).

6.3.1. Setting a simple Call Forward

Go to your Subscriber Preferences and click Edit on the Call Forward Type you want to set (e.g. Call Forward Unconditional).

Create Simple Call Forward

If you select URI/Number in the Destination field, you also have to set a URI/Number. The timeout defines for how long this destination should be tried to ring.

6.3.2. Advanced Call Hunting

Beside call forwarding to a single destination, Sipwise NGCP offers the possibility to activate call forwarding in a more sophisticated way:

  • to multiple destinations (→ Destination Set)
  • only during a pre-defined time set (→ Time Set)
  • only for specific callers (→ Source Set)

If you want to define such more detailed call forwarding rules, you need to change into the Advanced View when editing your call forward. There, you can select multiple Destination Set - Time Set - Source Set triples that determine all conditions under which the call will be forwarded.

Explanation of call forward parameters

6.3.2.1. Configuring Destination Sets

Click on Manage Destination Sets to see a list of available sets. The quickset_cfu has been implicitly created during our creation of a simple call forward. You can edit it to add more destinations, or you can create a new destination set.

Create CF Destination Set

When you close the Destination Set Overview, you can now assign your new set in addition or instead of the quickset_cfu set.

Assign CF Destination Sets

Press Save to store your settings.

6.3.2.2. Configuring Time Sets

Click on Manage Time Sets in the advanced call-forward menu to see a list of available time sets. By default there are none, so you have to create one.

Create CF Time Set

You need to provide a Name, and a list of Periods where this set is active. If you only set the top setting of a date field (like the Year setting in our example above), then it’s valid for just this setting (like the full year of 2013 in our case). If you provide the bottom setting as well, it defines a period (like our Month setting, which means from beginning of April to end of September). For example, if a CF is set with the following timeset: "hour { 10-12 } minute { 20-30 }", the CF will be matched within the following time ranges:

  • from 10.20am to 10:30am
  • from 11.20am to 11:30am
  • from 12.20am to 12:30am
important

the period is a through definition, so it covers the full range. If you define an Hour definition 8-16, then this means from 08:00 to 16:59:59 (unless you filter the Minutes down to something else).

If you close the Time Sets management, you can assign your new time set to the call forwards you’re configuring.

6.3.2.3. Configuring Source Sets

Once the Advanced View of the call forward definition has been opened, you will need to press the Manage Source Sets button to start defining new Source Sets or managing an existing one. The following image shows the Source Set definition dialog:

Creating a Call Forward Source Set

Figure 32. Creating a Call Forward Source Set


You will need to fill in the Name field first, then in Source field you can enter:

  • A simple phone number in E.164 format
  • A pattern, in order to define a range of numbers. You can use "*" (matches a string of 0 to any number of characters), "?" (matches any single character), "[abc]" (matches a single character that is part of the explicitly listed set: a, b or c) and "[0-9]" (matches a single character that falls in the range 0 to 9) as wildcards, as usual in shell patterns. Examples:

    • "431*" (all numbers from Vienna / Austria)
    • "49176[0-5]77*" (German numbers containing fixed digits and a variable digit in 0-5 range in position 6)
    • "43130120??" (numbers from Vienna with fixed prefix and 2 digits variable at the end)
  • The constant string "anonymous" that indicates a suppressed calling number (CLIR)

You can add more patterns to the Source Set by pressing the Add another source button. When you finished adding all patterns, press the Save button. You will then see the below depicted list of Source Sets:

List of Call Forward Source Sets

Figure 33. List of Call Forward Source Sets


As a next step you can define a Destination Set as described in Destination Sets Section 6.3.2.1, “Configuring Destination Sets” subchapter. For our example, we have defined the following Destination Set:

List of Call Forward Destination Sets

Figure 34. List of Call Forward Destination Sets


A final step of defining the call forward settings is selecting a Destination, a Time and a Source Set, as shown in the image below. Please note that there is no specific Time Set selected in our example, that means the call forward rule is valid (as shown) <always>.

Definition of a Call Forward with Source and Destination Sets

Figure 35. Definition of a Call Forward with Source and Destination Sets


Once all the settings have been defined and the changes are saved, you will see the call forward entry (in our example: Call Forward Unconditional), with the names of the selected Destination, Time and Source Sets provided, at Subscriber Preferences → Call Forwards location on the web interface:

List of Call Forward with Source and Destination Sets

Figure 36. List of Call Forward with Source and Destination Sets


6.4. Local Number Porting

The Sipwise NGCP platform comes with two ways of accomplishing local number porting (LNP):

  • one is populating the integrated LNP database with porting data,
  • the other is accessing external LNP databases via the Sipwise LNP daemon using the LNP API.
info

Accessing external LNP databases is available for PRO and CARRIER products only.

6.4.1. Local LNP Database

The local LNP database provides the possibility to define LNP Carriers (the owners of certain ported numbers or number blocks) and their corresponding LNP Numbers belonging to those carriers. It can be configured on the admin panel in SettingsNumber Porting or via the API. The LNP configuration can be populated individually or via CSV import/export both on the panel and the API.

6.4.1.1. LNP Carriers

LNP Carriers are defined by an arbitrary Name for proper identification (e.g. British Telecom) and contain a Prefix which can be used as routing prefix in LNP Rewrite Rules and subsequently in Peering Rules to route calls to the proper carriers. The LNP prefix is written to CDRs to identify the selected carrier for post processing and analytics purposes of CDRs. LNP Carrier entries also have an Authoritative flag indicating that the numbers in this block belong to the carrier operating the sip:provider PRO. This is useful to define your own number blocks, and in case of calls to those numbers reject the calls if the numbers are not assigned to local subscribers (otherwise they would be routed to a peer, which might cause call loops). Finally the Skip Rewrite flag skips executing of LNP Rewrite Rules if no number manipulation is desired for an LNP carrier.

6.4.1.2. LNP Numbers

LNP Carriers contain one or more LNP Numbers. Those LNP Numbers are defined by a Number entry in E164 format (<cc><ac><sn>) used to match a number against the LNP database. Number matching is performed on a longest match, so you can define number blocks without specifying the full subscriber number (e.g. a called party number 431999123 is going to match an entry 431999 in the LNP Numbers).

For an LNP Numbers entry, an optional Routing Number can be defined. This is useful to translate e.g. premium 900 or toll-free 800 numbers to actual routing numbers. If a Routing Number is defined, the called party number is implicitly replaced by the Routing Number and the call processing is continued with the latter. For external billing purposes, the optional Type tag of a matched LNP number is recorded in CDRs.

An optional Start Date and End Date allows to schedule porting work-flows up-front by populating the LNP database with certain dates, and the entries are only going to become active with those dates. Empty values for start indicate a start date in the past, while empty values for end indicate an end time in the future during processing of a call, allowing to define infinite date ranges. As intervals can overlap, the LNP number record with a start time closest to the current time is selected.

6.4.1.3. Enabling local LNP support

In order to activate Local LNP during routing, the feature must be activated in config.yml. Set kamailioproxylnpenabled to yes and kamailioproxylnptype to local.

6.4.1.4. LNP Routing Procedure

Calls to non-authoritative Carriers

When a call arrives at the system, the calling and called party numbers are first normalized using the Inbound Rewrite Rules for Caller and Inbound Rewrite Rules for Callee within the rewrite rule set assigned to the calling party (a local subscriber or a peer).

If the called party number is not assigned to a local subscriber, or if the called party is a local subscriber and has the subscriber/domain preference lnp_for_local_sub set, the LNP lookup logic is engaged, otherwise the call proceeds without LNP lookup. The further steps assume that LNP is engaged.

If the call originated from a peer, and the peer preference caller_lnp_lookup is set for this peer, then an LNP lookup is performed using the normalized calling party number. The purpose for that is to find the LNP prefix of the calling peer, which is then stored as source_lnp_prefix in the CDR, together with the selected LNP number’s type tag (source_lnp_type). If the LNP lookup does not return a result (e.g. the calling party number is not populated in the local LNP database), but the peer preference default_lnp_prefix is set for the originating peer, then the value of this preference is stored in source_lnp_prefix of the CDR.

Next, an LNP lookup is performed using the normalized called party number. If no number is found (using a longest match), no further manipulation is performed.

If an LNP number entry is found, and the Routing Number is set, the called party number is replaced by the routing number. Also, if the Authoritative flag is set in the corresponding LNP Carrier, and the called party number is not assigned to a local subscriber, the call is rejected. This ensures that numbers allocated to the system but not assigned to subscribers are dropped instead of routed to a peer.

important

If the system is serving a local subscriber with only the routing number assigned (but not e.g. the premium number mapping to this routing number), the subscriber will not be found and the call will either be rejected if the called party premium number is within an authoritative carrier, or the call will be routed to a peer. This is due to the fact that the subscriber lookup is performed with the dialled number, but not the routing number fetched during LNP. So make sure to assign e.g. the premium number to the local subscriber (optionally in addition to the routing number if necessary using alias numbers) and do not use the LNP routing number mechanism for number mapping to local subscribers.

Next, if the the LNP carrier does not have the Skip Rewriting option set, the LNP Rewrite Rules for Callee are engaged. The rewrite rule set used is the one assigned to the originating peer or subscriber/domain via the rewrite_rule_set preference. The variables available in the match and replace part are, beside the standard variables for rewrite rules:

  • ${callee_lnp_prefix}: The prefix stored in the LNP Carrier
  • ${callee_lnp_basenumber}: The actual number entry causing the match (may be shorter than the called party number due to longest match)

Typically, you would create a rewrite rule to prefix the called party number with the callee_lnp_prefix by matching ^([0-9]+)$ and replacing it by ${callee_lnp_prefix}\1.

Once the LNP processing is completed, the system checks for further preferences to finalize the number manipulation. If the originating local subscriber or peer has the preference lnp_add_npdi set, the Request URI user-part is suffixed with ;npdi. Next, if the preference lnp_to_rn is set, the Request URI user-part is suffixed with ;rn=LNP_ROUTING_NUMBER, where LNP_ROUTING_NUMBER is the Routing Number stored for the number entry in the LNP database, and the originally called number is kept in place. For example, if lnp_to_rn is set and the number 1800123 is called, and this number has a routing number 1555123 in the LNP database, the resulting Request-URI is sip:1800123;rn=1555123@example.org.

Finally, the destination_lnp_prefix in the CDR table is populated either by the prefix defined in the Carrier of the LNP database if a match was found, or by the default_lnp_prefix prefrence of the destination peer or subscriber/domain.

6.4.1.5. Blocking Calls Using LNP Data

The Sipwise NGCP provides means to allow or block calls towards ported numbers that are hosted by particular LNP carriers. Please visit Section 6.2.2.2, “Creating Rules per NCOS Level” in the handbook to learn how this can be achieved.

6.4.1.6. Transit Calls using LNP

If a call originated from a peer and the peer preference force_outbound_calls_to_peer is set to force_nonlocal_lnp (the if callee is not local and is ported selection in the panel), the call is routed back to a peer selected via the peering rules.

This ensures that if a number once belonged to your system and is ported out, but other carriers are still sending calls to you (e.g. selecting you as an anchor network), the affected calls can be routed to the carrier the number got ported to.

6.4.1.7. CSV Format

The LNP database can be exported to CSV, and in the same format imported back to the system. On import, you can decide whether to drop existing data prior to applying the data from the CSV.

The CSV file format contains the fields in the following order:

carrier_name carrier_prefix number routing_number start end authoritative skip_rewrite

Table 2. LNP CSV Format

Name

Description

Carrier Name

The Name in the LNP Carriers table (string, e.g. My Carrier)

Carrier Prefix

The Prefix in the LNP Carriers table (string, e.g. DD55)

Number

The Number in the LNP Numbers table (E164 number, e.g. 1800666)

Routing Number

The Routing Number in the LNP Numbers table (E164 number or empty, e.g. 1555666)

Start

The Start in the LNP Numbers table (YYYY-MM-DD or empty, e.g. 2016-01-01)

End

The End in the LNP Numbers table (YYYY-MM-DD or empty, e.g. 2016-12-30)

Authoritative

The Authoritative flag in the LNP Carriers table (0 or 1)

Skip Rewrite

The Skip Rewrite flag in the LNP Carriers table (0 or 1)

Type

The Type tag in the LNP Numbers table (alphanumeric string, e.g. mobile)


6.4.2. External LNP via LNP API

External LNP relies on the Sipwise LNP Daemon (lnpd) which kamailio-proxy is talking to via a defined JSONRPC protocol. The proxy sends the A and B number to lnpd, which in the current release translates it to a SIP Message sent to an external server (typically a Squire SIP-to-INAP gateway. This external gateway is performing an SS7 INAP request to fetch the LNP result, which is passed back as a binary blob in a 3xx response to the lnpd. The lnpd extracts the TCAP body of the response and returns the information back to the proxy.

6.4.2.1. Enabling LNP lookup via API

In order to activate LNP lookup via API during call routing, the feature must be activated in /etc/ngcp-config/config.yml. Set these parameters:

  • kamailio→proxy→lnp→enabled : yes
  • kamailio→proxy→lnp→type : api
  • lnpd→enabled : yes

There is a possibility to explicitly allow (whitelist) or deny (blacklist) certain number ranges for which an LNP lookup may be done. The relevant configuration parameters are at kamailio→proxy→lnp→lnp_request_whitelist and kamailio→proxy→lnp→lnp_request_blacklist. For each entry in the list a POSIX regex expression may be used, see the following example:

    lnp:
      lnp_request_whitelist:
        - '^9'
        - '^800'
      lnp_request_blacklist:
        - '^1'
        - '^900'
        - '^110'
        - '^112'

Interpretation of the above lists (that are based on numbers represented in national format):

  • whitelist: do LNP lookup for any called number that starts with 9 or 800
  • blacklist: do not perform LNP lookup for any called number that starts with 1, 900, 110 or 112
important

If both whitelist and blacklist are defined, the LNP lookup is only performed when the called number matches any of the whitelist patterns and does not match any of the blacklist patterns.

6.4.2.2. The Redundancy Feature

It is possible to set up LNP daemon to provide a kind of redundant service to the Proxy. This means the LNP daemon will send its LNP query to more LNP serving nodes that are predefined in a list. (See Configuration of LNP daemon Section 6.4.2.3, “Configuration of Sipwise LNP Daemon” chapter for details.) The LNP query may happen in 2 ways:

  • round-robin: LNP daemon sends the query to one of the serving nodes then waits for the response for a configurable timeout. If it does not get the response in time, it sends the LNP query to the next serving node.
  • parallel: LNP daemon sends the query to all of the serving nodes then waits for the response, and will accept the first response that it receives.
6.4.2.3. Configuration of Sipwise LNP Daemon

LNP daemon takes its active configuration from /etc/ngcp-lnpd/config.yml file. The file is generated automatically — when a new NGCP configuration is applied (ngcpcfg apply…) — from the main Sipwise NGCP configuration file: /etc/ngcp-config/config.yml and a template: /etc/ngcp-config/template/etc/ngcp-lnpd/config.yml.tt2. System administrators are only expected to modify the lnpd.config section of main configuration file /etc/ngcp-config/config.yml.

A sample LNP daemon configuration file (/etc/ngcp-lnpd/config.yml) looks like:

daemon:
        json-rpc:
                ports:
                        - 54321
                        - 12345
                interfaces:
                        - 127.0.0.1
                        - 192.168.1.90
                        - ::1

        sip:
                port: 5095
                address: 0.0.0.0

        threads: 4
        foreground: false
        pidfile: /tmp/lnpd.pid
        loglevel: 7

instances:
        default:
                module: sigtran
                destination: 192.168.1.99
                from-domain: test.example.com
                headers:
                        - header: INAP-Service-Key
                          value: 2
                reply:
                        tcap: raw-tcap
        redundant:
                module: sigtran
                destinations:
                        - 192.168.1.99
                        - 192.168.1.95
                        - 192.168.1.90
                mechanism: round-robin
                retry-time: 30
                timeout: 5
                from-domain: test.example.com
                headers:
                        - header: INAP-Service-Key
                          value: 2
                reply:
                        tcap: raw-tcap
        parallel:
                module: sigtran
                destinations:
                        - 192.168.1.99
                        - 192.168.1.95
                        - 192.168.1.90
                mechanism: parallel
                retry-time: 30
                timeout: 10
                from-domain: test.example.com
                headers:
                        - header: INAP-Service-Key
                          value: 2
                reply:
                        tcap: raw-tcap
        mock1:
                module: mock-tcap
                numbers:
                        - number: '4311003'
                          routing-number: '4318881003'
                reply:
                        tcap: raw-tcap

The corresponding NGCP main configuration file contains:

    daemon:
      foreground: 'false'
      json-rpc:
        ports:
          - '54321'
          - '12345'
      loglevel: '7'
      sip:
        port: '5095'
      threads: '4'
    instances:
    << These are the same entries as in /etc/ngcp-lnpd/config.yml file >>

Description of configuration parameters in /etc/ngcp-config/config.yml file

  • daemon section:

    • foreground: determines if the LNP daemon runs as foreground or background process
    • json-rpc.ports: port numbers where LNP daemon listens for incoming JSONRPC requests from NGCP Proxy
    • loglevel: how detailed information LNP daemon writes in its log file
    • sip.port: listening port number used for SIP sessions with LNP serving nodes; LNP daemon will listen on first available (shared) IP address that is taken from /etc/ngcp-config/network.yml file
    • threads: number of threads LNP daemon will use internally; this value determines how many requests the daemon can serve in parallel
  • instances section: at least one default instance must be defined here. Others are also useful for providing redundancy, please check redundant and parallel entries above.

    • module: only sigtran is used for normal operations

      important

      The module mock-tcap is only meant for developers. In this case the LNP daemon does not produce a SIP request that it sends to LNP serving nodes, but instead it uses the numbers parameter to match a called number with a routing number. The numbers parameter contains a list of number — routing-number pairs and is used as a database for number lookups. Finally LNP daemon returns the routing number as a response on LNP query.

    • destinations: list of nodes to which LNP daemon sends the LNP query
    • mechanism: either parallel or round-robin, defining the method of redundant queries
    • retry-time: a period of time in seconds while LNP daemon considers an LNP serving node being unreachable after an LNP query timeout
    • timeout: the period of time while LNP daemon waits for a response on an LNP query from one of the LNP serving nodes

      PLEASE NOTE: retry-time and timeout are used with both the parallel and the round-robin redundancy methods

    • from-domain: the domain that will be used in SIP From header when LNP daemon sends the LNP query
    • headers: this is a list of header name — value pairs; these custom headers will be included in SIP request that LNP daemon sends to an LNP serving node
    • reply.tcap: determines the format of reply sent to NGCP Proxy; currently only raw-tcap is supported, which means LNP daemon will not decode the TCAP response it gets from an LNP serving node but it forwards the raw TCAP message body

6.5. Emergency Mapping

As opposed to the Simple Emergency Number Handling Section 5.7.5.1, “Simple Emergency Number Handling Overview” solution, the Sipwise NGCP supports an advanced emergency call handling method, called emergency mapping. The main idea is: instead of obtaining a statically assigned emergency prefix / suffix from subscriber preferences, NGCP retrieves an emergency routing prefix from a central emergency call routing table, according to the current location of the calling subscriber.

The following figure shows the overview of emergency call processing when using emergency mapping feature:

Emergency Call Handling with Mapping

Figure 37. Emergency Call Handling with Mapping


6.5.1. Emergency Mapping Description

Emergency numbers per geographic location are mapped to different routing prefixes not deriveable from an area code or the emergency number itself. This is why a global emergency mapping table related to resellers is introduced, allowing to map emergency numbers to their geographically dependent routing numbers.

The geographic location is referenced by a location ID, which has to be populated by a north-bound provisioning system. No towns, areas or similar location data is stored on the NGCP platform. The locations are called Emergency Containers on NGCP.

The actual emergency number mapping is done per location (per Emergency Container), using the so-called Emergency Mapping entries. An Emergency Mapping entry assigns a routing prefix, valid only in a geographic area, to a generic emergency number (for example 112 in Europe, 911 in the U.S.A.) or a country specific one (for example 133).

info

As of mr4.5 version, the NGCP performs an exact match on the emergency number in the emergency routing table.

Emergency Containers may be assigned to various levels of the client hierarchy within NGCP. The following list shows such levels with each level overriding the settings of the previous one:

  1. Customer or Domain
  2. Customer Location, which is a territory representing a subset of the customer’s subscribers, defined as one or more IP subnets.
  3. Subscriber
info

Please be aware that Customer Location is not necessarily identical to the "location" identified through an Emergency Container.

Once the emergency routing prefix has been retrieved from the emergency mapping table, call processing continues in the same way as in case of simple emergency call handling.

6.5.2. Emergency Mapping Configuration

The administrative web panel of NGCP provides the configuration interface for emergency mapping. Please navigate to Settings → Emergency Mapping menu item first, in order to start configuring the mapping.

An Emergency Container must be created, before the mapping entries can be defined. Press Create Emergency Container to start this. An example of a container is shown here:

Creating an Emergency Container

Figure 38. Creating an Emergency Container


You have to select a Reseller that this container belongs to, and enter a Name for the container, which is an arbitrary text.

tip

The platform administrator has to create as many containers as the number of different geographic areas (locations) the subscribers are expected to be in.

As the second step of emergency mapping provisioning, the Emergency Mapping entries must be created. Press Create Emergency Mapping to start this step. An example is shown here:

Creating an Emergency Mapping Entry

Figure 39. Creating an Emergency Mapping Entry


The following parameters must be set:

  • Container: select an emergency mapping container (i.e. a location ID)
  • Code: the emergency number that subscribers will dial
  • Prefix: the routing prefix that belongs to the particular emergency service within the selected location

Once all the necessary emergency mappings have been defined, the platform administrator will see a list of containers and mapping entries:

Emergency Mapping List

Figure 40. Emergency Mapping List


The emergency number mapping is now defined. As the next step, the platform administrator has to assign the emergency containers to Customers / Domains / Customer Locations or Subscribers. We’ll take an example with a Customer: select the customer, then navigate to Details → Preferences → Number Manipulations. In order to assign a container, press the Edit button and then select one container from the drop-down list:

Assigning an Emergency Mapping Container

Figure 41. Assigning an Emergency Mapping Container


Rewrite Rules for Emergency Mapping

Once emergency containers and emergency mapping entries are defined, the NGCP administrator has to ensure that the proper number manipulation takes place, before initiating any emergency call towards peers.

important

Please don’t forget to define the rewrite rules for peers — particularly: Outbound Rewrite Rules for Callee — as described in Normalize Emergency Calls for Peers Section 5.7.5.3, “Normalize Emergency Calls for Peers” section of the handbook.

6.5.2.1. Emergency Calls Not Allowed

There is a special case when the dialed number is recognized as an emergency number, but the emergency number is not available for the geographic area the calling party is located in.

In such a case the emergency mapping lookup will return an emergency prefix, but the value of this will be NULL. Therefore the call is rejected and an announcement is played. The announcement is a newly defined sound file referred as emergency_geo_unavailable.

It is possible to configure the rejection code and reason in /etc/ngcp-config/config.yml file, the parameters are: kamailio.proxy.early_rejects.emergency_invalid.announce_code and kamailio.proxy.early_rejects.emergency_invalid.announce_reason.

6.5.2.2. Bulk Upload or Download of Emergency Mapping Entries

The Sipwise NGCP offers the possibility to upload / download emergency mapping entries in form of CSV files. This operation is available for each reseller, and is very useful if a reseller has many mapping entries.

Downloading Emergency Mapping List

One has to navigate to Settings → Emergency Mapping menu and then press the Download CSV button to get the list of mapping entries in a CSV file. First the reseller must be selected, then the Download button must be pressed. As an example, the entries shown in "Emergency Mapping List" picture above would be written in the file like here below:

EmergCont_1,133,E1_133_
EmergCont_1,144,E1_144_
EmergCont_2,133,E2_133_

The CSV file has a plain text format, each line representing a mapping entry, and contains the following fields:

  • Container name, as defined in Emergency Containers
  • Emergency Number
  • Emergency Prefix

Uploading Emergency Mapping List

Uploading a CSV file with emergency mapping entries may be started after pressing the Upload CSV button. The following data must be provided:

  • Reseller: selected from the list
  • Upload mapping: the CSV file must be selected after pressing the Choose File button
  • Purge existing: an option to purge existing emergency mapping entries that belong to the selected reseller, before populating the new mapping data from the file
Uploading Emergency Mapping Data

Figure 42. Uploading Emergency Mapping Data


The CSV file for the upload has the same format as the one used for download.

6.6. Header Manipulation

6.6.1. Header Filtering

Adding additional SIP headers to the initial INVITEs relayed to the callee (second leg) is possible by modifying the following template file: /etc/ngcp-config/templates/etc/ngcp-sems/etc/ngcp.sbcprofile.conf.customtt.tt2. The following section can be changed:

header_filter=whitelist
header_list=[%IF kamailio.proxy.debug == "yes"%]P-NGCP-CFGTEST,[%END%]
P-R-Uri,P-D-Uri,P-Preferred-Identity,P-Asserted-Identity,Diversion,Privacy,
Allow,Supported,Require,RAck,RSeq,Rseq,User-Agent,History-Info,Call-Info
[%IF kamailio.proxy.presence.enable == "yes"%],Event,Expires,
Subscription-State,Accept[%END%][%IF kamailio.proxy.allow_refer_method
== "yes"%],Referred-By,Refer-To,Replaces[%END%]

By default the system will remove from the second leg all the SIP headers which are not in the above list. If you want to keep some additional/custom SIP headers, coming from the first leg, into the second leg you just need to add them at the end of the header_list= list. After that, as usual, you need to apply and push the changes. In this way the system will keep your headers in the INVITE sent to the destination subscriber/peer.

warning

DO NOT TOUCH the list if you don’t know what you are doing.

6.6.2. Codec Filtering

Sometimes you may need to filter some audio CODEC from the SDP payload, for example if you want to force your subscribers to do not talk a certain codecs or force them to talk a particular one. To achieve that you just need to change the /etc/ngcp-config/config.yml, in the following section:

sdp_filter:
      codecs: PCMA,PCMU,telephone-event
      enable: yes
      mode: whitelist

In the example above, the system is removing all the audio CODECS from the initial INVITE except G711 alaw,ulaw and telephone-event. In this way the callee will be notified that the caller is able to talk only PCMA. Another example is the blacklist mode:

sdp_filter:
      codecs: G729,G722
      enable: yes
      mode: blacklist

In this way the G729 and G722 will be removed from the SDP payload. In order to apply the changes, as usual, you need to run ngcpcfg apply Enable CODEC filtering and push the changes .

6.6.3. Enable History and Diversion Headers

It may be useful and mandatory - specially with NGN interconnection - to enable SIP History header and/or Diversion header for outbound requests to a peer or even for on-net calls. In order to do so, you should enable the following preferences in Domain’s and Peer’s Preferences:

  • Domain’s Prefererences: inbound_uprn = Forwarder’s NPN
  • Peer’s Prefererences: outbound_history_info = UPRN
  • Peer’s Prefererences: outbound_diversion = UPRN
  • Domain’s Prefererences: outbound_history_info = UPRN (if you want to allow History Header for on-net call as well)
  • Domain’s Prefererences: outbound_diversion = UPRN (if you want to allow Diversion Header for on-net call as well)

6.7. SIP Trunking with SIPconnect

6.7.1. User provisioning

For the purpose of external SIP-PBX interconnect with sip:provider PRO the platform admin should create a subscriber with multiple aliases representing the numbers and number ranges served by the SIP-PBX.

  • Subscriber username - any SIP username that forms an "email-style" SIP URI.
  • Subscriber Aliases - numbers in the global E.164 format without leading plus.

To configure the Subscriber, go to SettingsSubscribers and click Details on the row of your subscriber. There, click on the Preferences button on top.

You should look into the Number Manipulations and Access Restrictions sections in particular, which control the calling and called number presentation.

6.7.2. Inbound calls routing

Enable preference Number Manipulationse164_to_ruri for routing inbound calls to SIP-PBX. This ensures that the Request-URI will comprise a SIP-URI containing the dialed alias-number as user-part, instead of the user-part of the registered AOR (which is normally a static value).

6.7.3. Number manipulations

The following sections describe the recommended configuration for correct call routing and CLI presentation according to the SIPconnect 1.1 recommendation.

6.7.3.1. Rewrite rules

The SIP PBX by default inherits the domain dialplan which usually has rewrite rules applied to normal Class 5 subscribers with inbound rewrite rules normalizing the dialed number to the E.164 standard. If most users of this domain are Class 5 subscribers the dialplan may supply calling number in national format - see Section 5.7, “Configuring Rewrite Rule Sets”. While the SIP-PBX trunk configuration can be sometimes amended it is a good idea in sense of SIPconnect recommendation to send only the global E.164 numbers.

Moreover, in mixed environments with the sip:provider PRO Cloud PBX sharing the same domain with SIP trunking (SIP-PBX) customers the subscribers may have different rewrite rules sets assigned to them. The difference is caused by the fact that the dialplan for Cloud PBX is fundamentally different from the dialplan for SIP trunks due to extension dialing, where the Cloud PBX subscribers use the break-out code (see Section 17.1.2, “Preparing PBX Rewrite Rules”) to dial numbers outside of this PBX.

The SIPconnect compliant numbering plan can be accommodated by assigning Rewrite Rules Set to the SIP-PBX subscriber. Below is a sample Rewrite Rule Set for using the global E.164 numbers with plus required for the calling and called number format compliant to the recommendation.

Inbound Rewrite Rule for Caller

  • Match Pattern: ^(00|\+)([1-9][0-9]+)$
  • Replacement Pattern: \2
  • Description: International to E.164
  • Direction: Inbound
  • Field: Caller

Inbound Rewrite Rule for Callee

  • Match Pattern: ^(00|\+)([1-9][0-9]+)$
  • Replacement Pattern: \2
  • Description: International to E.164
  • Direction: Inbound
  • Field: Callee

Outbound Rewrite Rule for Caller

  • Match Pattern: ^([1-9][0-9]+)$
  • Replacement Pattern: +\1
  • Description: For the calls to SIP-PBX add plus to E.164
  • Direction: Outbound
  • Field: Caller

Outbound Rewrite Rule for Callee

  • Match Pattern: ^([1-9][0-9]+)$
  • Replacement Pattern: +\1
  • Description: For the calls to SIP-PBX add plus to E.164
  • Direction: Outbound
  • Field: Callee

Assign the aforementioned Rewrite Rule Set to the SIP-PBX subscribers.

warning

Outbound Rewrite Rules for Callee shall NOT be applied to the calls to normal SIP UAs like IP phones since the number with plus does not correspond to their SIP username.

6.7.3.2. User parameter

The following configuration is needed for your platform to populate the From and To headers and Request-URI of the INVITE request with "user=phone" parameter as per RFC 3261 Section 19.1.1 (if the user part of the URI contains telephone number formatted as a telephone-subscriber).

  • Domain’s Prefererences: outbound_from_user_is_phone = Y
  • Domain’s Prefererences: outbound_to_user_is_phone = Y
6.7.3.3. Forwarding number

The following is our common configuration that covers the calling number presentation in a variety of use-cases, including the incoming calls, on-net calls and Call Forward by the platform:

  • Domain’s Preferences: inbound_uprn = Forwarder’s NPN
  • Domain’s Preferences: outbound_from_user = UPRN (if set) or User-Provided Number
  • Domain’s Preferences: outbound_pai_user = UPRN (if set) or Network-Provided Number
  • Domain’s Preferences: outbound_history_info = UPRN (if the called user expects History-Info header)
  • Domain’s Preferences: outbound_diversion = UPRN (if the called user expects Diversion header)
  • Domain’s Preferences: outbound_to_user = Original (Forwarding) called user if the callee expects the number of the subscriber forwarding the call, otherwise leave default.

The above parameters can be tuned to operator specifics as required. You can of course override these settings in the Subscriber Preferences if particular subscribers need special settings.

tip

On outgoing call from SIP-PBX subscriber the Network-Provided Number (NPN) is set to the cli preference prefilled with main E.164 number. In order to have the full alias number as NPN on outgoing call set preference extension_in_npn = Y.

Externally forwarded call. If the call forward takes place inside the SIP-PBX it can use one of the following specification for signaling the diversion number to the platform:

  • using Diversion method (RFC 5806): configure Subscriber’s Prefererences: inbound_uprn = Forwarder’s NPN / Received Diversion
  • using History-Info method (RFC 7044): NGCP platform extends the History-Info header received from the PBX by adding another level of indexing according to the specification RFC 7044.
6.7.3.4. Allowed CLIs
  • For correct calling number presentation on outgoing calls, you should include the pattern matching all the alias numbers of SIP-PBX or each individual alias number under the allowed_clis preference.
  • If the signalling calling number (usually taken from From user-part, see inbound_upn preferences) does not match the allowed_clis pattern, the user_cli or cli preference (Network-Provided Number) will be used for calling number presentation.

6.7.4. Registration

SIP-PBX can use either Static or Registration Mode. While SIPconnect 1.1 continues to require TLS support at MUST strength, one should note that using TLS for signaling does not require the use of the SIPS URI scheme. SIPS URI scheme is obsolete for this purpose.

Static Mode. While SIPconnect 1.1 allows the use of Static mode, this poses additional maintenance overhead on the operator. The administrator should create a static registration for the SIP-PBX: go to Susbcribers, DetailsRegistered DevicesCreate Permanent Registration and put address of the SIP-PBX in the following format: sip:username@ipaddress:5060 where username=username portion of SIP URI and ipaddress = IP address of the device.

Registration Mode. It is recommended to use the Registration mode with SIP credentials defined for the SIP-PBX subscriber.

important

The use of RFC 6140 style "bulk number registration" is discouraged. The SIP-PBX should register one AOR with email-style SIP URI. The sip:provider PRO will take care of routing the aliases to the AOR with e164_to_ruri preference.

6.7.4.1. Trusted Sources

If a SIP-PBX cannot perform the digest authentication, you can authenticate it by its source IP address in sip:provider PRO. To configure the IP-based authentication, go to the subscriber’s preferences (DetailsPreferencesTrusted Sources) and specify the IP address of the SIP-PBX in the Source IP field.

To authenticate multiple subscribers from the same IP address, use theFrom field to distinguish these subscribers.

When this feature is configured for a subscriber, the sip:provider PRO authenticates all calls that arrive from the specified IP address without challenging them.

important

If the same IP address and the FROM field are mistakenly specified as trusted for different subscribers, the sip:provider PRO will not know which subscriber to charge for the call and will randomly select one.

6.8. Trusted Subscribers

In some cases, when you have a device that cannot authenticate itself against sip:provider PRO, you may need to create a Trusted Subscriber. Trusted Subscribers use IP-based authentication and they have a Permanent SIP Registration URI in order to receive messages from sip:provider PRO.

In order to make a regular subscriber trusted, perform the following extra steps: * Create a permanent registration via (SubscribersDetailsRegistered DevicesCreate Permanent Registration) * Add the IP address of the device as Trusted Source in your subscriber’s preferences (DetailsPreferencesTrusted Sources).

This way, all SIP messages coming from the device IP will be considered trusted (and get authenticated just by the source IP). All the SIP messages forwarded to the devices will be sent to the SIP URI specified in the subscriber’s permanent registration.

6.9. Peer Probing

The basic way of selecting the appropriate peering server, where an outbound call can be routed to, has already been described in Section 5.6.2.3, “Routing Order Selection” of the handbook.

This chapter provides information on the peer probing feature of NGCP that is available since mr5.4.1 release.

6.9.1. Introduction to Peer Probing Feature

The Sipwise NGCP provides web admin panel and API capabilities to configure peering servers in order to terminate calls to non-local subscribers. Those peering servers may become temporarily unavailable due to overloading or networking issues. The NGCP will fail over to another peering server (matching the corresponding peering rules) after a timeout configured at system level (see sems.sbc.outbound_timeout configuration parameter; 6 sec by default), if no provisional response (a response with a code in the range of 100 to 199) is received for the outbound INVITE request.

Even if this timer is set much lower, like 3 sec, the call setup time is increased significantly. This is even more true if multiple peering servers fail at the same time, which will sum up the individual timeouts, finally causing call setup times reach the order of tens of seconds.

To optimize the call setup time in such scenarios, a new feature is implemented to continuously probe peering servers via SIP messages, and mark them as unavailable on timeout or when receiving unexpected response codes. Appropriate SIP response codes from the peering servers will mark them as available again.

Peering servers marked as unavailable are then skipped during call routing in the peering selection process, which significantly shortens the call setup times if peering servers fail.

6.9.2. Configuration of Peer Probing

The system administrator has to configure the peer probing feature in 2 steps:

  1. System-level configuration enables the peer probing feature in general on the NGCP and determines the operational parameters, such as timeouts, the SIP method used for probing requests, etc.
  2. Peering server configuration will add / remove a peering server to the list of probed endpoints.
6.9.2.1. System-level Configuration

The parameters of peer probing are found in the main system configuration file /etc/ngcp-config/config.yml. You can see the complete list of configuration parameters in Section 1.14, “kamailio” of the handbook, while the most significant ones are discussed here.

Enabling peer probing system-wide happens through the kamailio.proxy.peer_probe.enable parameter. If it is set to yes (which is the default value) then NGCP will consider probing of individual peering servers based on their settings.

Timeout of a single probing request can be defined through kamailio.proxy.peer_probe.timeout parameter. This is a value interpreted as seconds while NGCP will wait for a SIP response from the peering server. Default is 5 seconds.

The probing interval can be set through the kamailio.proxy.peer_probe.interval parameter. This is the time period in seconds that determines how often a probing request is sent to the peering servers. Default is 10 seconds.

The SIP method used for probing requests can be defined through kamailio.proxy.peer_probe.method parameter. Allowed values are: OPTIONS (default) and INFO.

tip

The system administrator, in most of the cases, will not need to modify the default configuration values other than that of timeout and interval.

If no available peering server is found, the call is rejected with the response code and reason configured in kamailio.proxy.early_rejects.peering_unavailable.announce_code and kamailio.proxy.early_rejects.peering_unavailable.announce_reason. If a sound file is configured within the system sound set assigned to the calling party, an announcement is played as early media before the rejection.

6.9.2.2. Individual Peering Server Configuration

When the peer probing feature is enabled on system-level, it is possible to add each individual peering server to the list of probed endpoints. You can change the probed status of a server in two ways:

Enable probing of a peering server via the admin web interface

  1. Open the properties panel of a peering server: Peerings → select a peering group → Details → select a peering server → Edit
  2. Tick the checkbox Enable Probing
  3. Save changes
Enable Probing of Peering Server

Figure 43. Enable Probing of Peering Server


Enable probing of a peering server via the REST API

In all cases you have to set the probe property to true in order to enable probing, and to false in order to disable probing. Default value is false and this property may be omitted in a create/update request, which ensures backward compatibility of the /api/peeringservers API resource.

6.9.3. Monitoring of Peer Probing

Peering server states, such as "reachable" / "unreachable", are continuously stored in a time-series database (InfluxDB type) by NGCP Proxy nodes. It is possible to graphically represent the state of peering servers on NGCP’s admin web interface, just like other system variables (like CPU and memory usage, number of registered subscribers, etc.). However this is not available by default and must be configured by Sipwise.

State changes of peering servers are also reported by means of SNMP traps. Each time the reachable state of one of the monitored peering servers changes, NGCP will send an SNMP trap, raising or clearing the alarm.

The Sipwise MIB is extended by a table of peers per proxy, containing the peer ID and the peer name, along with the peer probe status. An external monitoring system can poll the peers table via SNMP to gather the peer status from each proxy’s point of view.

The peer status can be obtained through the following route / OID:

 ...enterprises.sipwise.ngcp.ngcpObjects.ngcpMonitor.ngcpMonitorPeering.psTable.psEntry.psPeerStatus

 .1.3.6.1.4.1.34274.1.1.2.40.2.1.7

Value of psPeerStatus can be:

  • 0: unknown
  • 1: administratively down
  • 2: administratively up
  • 3: probed, pending
  • 4: probed, down
  • 5: probed, up

6.9.4. Further Details for Advanced Users

tip

This subchapter of the handbook is targeted on advanced system operators and Sipwise engineers and is not necessary to read in order to properly manage peer probing feature of NGCP.

6.9.4.1. Behaviour of Kamailio Proxy Instances

Each kamailio-proxy instance on the proxy nodes performs the probing individually for performance reasons. Each proxy holds its result in its cache to avoid central storage and replication of the probing results. Each proxy will send an SNMP trap if it detects a state change for a peering server, because proxies might be geographically distributed along with their load-balancers and can therefore experience different probing results.

Each peering server is cross-checked against the hash table filled during outbound probing requests and is skipped by call routing logic, if a match is found.

On start or restart of the kamailio-proxy instance, the probing will start after the first interval, and NOT immediately after start. In the first probing interval the proxy will always try to send call traffic to peering servers until the first probing round is finished, and will only then start to skip unavailable peering servers.

6.9.4.2. Changes to Kamailio Proxy Configuration

A new configuration template: /etc/ngcp/config/templates/etc/kamailio/proxy/probe.cfg.tt2 is introduced to handle outbound probing requests.

6.9.4.3. Database Changes

A new DB column: provisioning.voip_peer_hosts.probe with type TINYINT(1) (boolean) is added to the DB schema.

A peer status change will populate the kamailio.dispatcher table, inserting the SIP URI in format sip:$ip:$port;transport=$transport in dispatcher group 100, which defines the probing group for peering servers.

Also the kamailio.dispatcher.attrs column is populated with a parameter peerid=$id. This ID is used during probing to load the peer preferences: outbound_socket and lbrtp_set, that are required to properly route the probing request.

6.10. Fax Server

There is a Fax Server included in the sip:provider PRO. The following sections describe its architecture.

The Fax Server is included on the platform and requires no additional hardware. It supports both T38 and G711 codecs and provides a cost-effective paper-free office solution.

For the details of Fax Server configuration options, please see Faxserver Configuration Appendix C, NGCP-Faxserver Configuration chapter in this handbook.

6.10.1. Fax2Mail Architecture

To receive faxes via email, a phone call from a sender is connected to the fax application module (Asterisk + NGCP Fax Server) on the sip:provider PRO. The received fax document is converted to the format the receiver has configured (either PS, PDF or TIFF) via the components outlined in the figure below. The email is delivered to one or more configured addresses.

Software-Based Fax2Mail

6.10.2. Sendfax and Mail2Fax Architecture

To send faxes via the sip:provider PRO a sender can use any email client or an interface such as Webfax or REST API.

Currently, supported formats are TXT, PS, TIFF and PDF.

The document is sent to the NGCP Fax Server instance on the sip:provider PRO. Once successfully queued by the fax server, it is converted to an internal TIFF format and is sent via the components outlined in the below figure to the specified phone number. Of course, a fax device that can receive the document must be connected on the destination side.

Software-Based Mail2Fax

6.11. Voicemail System

6.11.1. Accessing the IVR Menu

For a subscriber to manage his voicebox via IVR, there are two ways to access the voicebox. One is to call the URI voicebox@yourdomain from the subscriber itself, allowing password-less access to the IVR, as the authentication is already done on SIP level. The second is to call the URI voiceboxpass@yourdomain from any number, causing the system to prompt for a mailbox and the PIN. The PIN can be set in the Voicemail and Voicebox section of the Subscriber Preferences.

6.11.1.1. Mapping numbers and codes to IVR access

Since access might need to be provided from external networks like PSTN/Mobile, and since certain SIP phones do not support calling alphanumeric numbers to dial voicebox, you can map any number to the voicebox URIs using rewrite rules.

To do so, you can provision a match pattern e.g. ^(00|\+)12345$ with a replace pattern voicebox or voiceboxpass to map a number to either password-less or password-based IVR access respectively. Create a new rewrite rule with the Inbound direction and the Callee field in the corresponging rewrite rule set.

For inbound calls from external networks, assign this rewrite rule set to the corresponding incoming peer. If you also need to map numbers for on-net calls, assign the rewrite rule set to subscribers or the whole SIP domain.

6.11.1.2. External IVR access

When reaching voiceboxpass, the subscriber is prompted for her mailbox number and a password. All numbers assigned to a subscriber are valid input (primary number and any alias number). By default, the required format is in E.164, so the subscriber needs to enter the full number including country code, for example 4912345 if she got assigned a German number.

You can globally configure a rewrite rule in config.yml using asterisk.voicemail.normalize_match and asterisk.voicemail.normalize_replace, allowing you to customize the format a subscriber can enter, e.g. having ^0([1-9][0-9]+)$ as match part and 49$1 as replace part to accept German national format.

6.11.2. IVR Menu Structure

The following list shows you how the voicebox menu is structured.

  • 1 Read voicemail messages

    • 3 Advanced options

      • 3 To Hear messages Envelope
      • * Return to the main menu
    • 4 Play previous message
    • 5 Repeat current message
    • 6 Play next message
    • 7 Delete current message
    • 9 Save message in a folder

      • 0 Save in new Messages
      • 1 Save in old Messages
      • 2 Save in Work Messages
      • 3 Save in Family Messages
      • 4 Save in Friends Messages
      • # Return to the main menu
  • 2 Change folders

    • 0 Switch to new Messages
    • 1 Switch to old Messages
    • 2 Switch to Work Messages
    • 3 Switch to Family Messages
    • 4 Switch to Friends Messages
    • # Get Back
  • 3 Advanced Options

    • * To return to the main menu
  • 0 Mailbox options

    • 1 Record your unavailable message

      • 1 accept it
      • 2 Listen to it
      • 3 Rerecord it
    • 2 Record your busy message

      • 1 accept it
      • 2 Listen to it
      • 3 Rerecord it
    • 3 Record your name

      • 1 accept it
      • 2 Listen to it
      • 3 Rerecord it
    • 4 Record your temporary greetings

      • 1 accept it / or re-record if one already exist
      • 2 Listen to it / or delete if one already exist
      • 3 Rerecord it
    • 5 Change your password
    • * To return to the main menu
  • * Help
  • # Exit

6.11.3. Type Of Messages

A message/greeting is a short message that plays before the caller is allowed to record a message. The message is intended to let the caller know that you are not able to answer their call. It can also be used to convey other information like when you will be available, other methods to contact you, or other options that the caller can use to receive assistance.

The IVR menu has three types of greetings.

6.11.3.1. Unavailable Message

The standard voice mail greeting is the "unavailable" greeting. This is used if you don’t answer the phone and so the call is directed to your voice mailbox.

  • You can record a custom unavailable greeting.
  • If you have not recorded your unavailable greeting but have recorded your name, the system will play a generic message like: "Recorded name is unavailable."
  • If you have not recorded your unavailable greeting, the phone system will play a generic message like: "Digits-of-number-dialed is unavailable".
6.11.3.2. Busy Message

If you wish, you can record a custom greeting used when someone calls you and you are currently on the phone. This is called your "Busy" greeting.

  • You can record a custom busy greeting.
  • If you have not recorded your busy greeting but have recorded your name, the phone system will play a generic message: "Recorded name is busy."
  • If you have not recorded your busy greeting and have not recorded your name (see below), the phone system will play a generic message: "Digits-of-number-dialed is busy."
6.11.3.3. Temporary Greeting

You can also record a temporary greeting. If it exists, a temporary greeting will always be played instead of your "busy" or "unavailable" greetings. This could be used, for example, if you are going on vacation or will be out of the office for a while and want to inform people not to expect a return call anytime soon. Using a temporary greeting avoids having to change your normal unavailable greeting when you leave and when you come back.

6.11.4. Folders

The Voicemail system allows you to save and organize your messages into folders. There can be up to ten folders.

6.11.4.1. The Default Folder List
  • 0 - New Messages
  • 1 - Old Messages
  • 2 - Work Messages
  • 3 - Family Messages
  • 4 - Friends Messages

When a caller leaves a message for you,the system will put the message into the "New Messages" folder. If you listen to the message, but do not delete the message or save the message to a different folder, it will automatically move the message to the "Old Messages" folder. When you first log into your mailbox, the Voicemail System will make the "New Messages" folder the current folder if you have any new messages. If you do not have any new messages the it will make the "Old Messages" folder the current folder.

6.11.5. Voicemail Languages Configuration

To add a new language or to change the pronunciation for an existing one, ensure that mode=new is defined in /etc/ngcp-config/templates/etc/asterisk/say.conf.tt2. Adjust the configuration in the same file using the manual in the beginning. Then, as usual, make the new configuration active.

6.11.6. Flowcharts with Voice Prompts

This section shows flowcharts of calls to the voicemail system. Flowcharts contain the name of prompts as they are identified among Asterisk voice prompts.

6.11.6.1. Listening to New Messages
Flowchart of Listening to New Messages

Figure 44. Flowchart of Listening to New Messages


6.11.6.2. Changing Voicemail Folders
Flowchart of Changing Voicemail Folders

Figure 45. Flowchart of Changing Voicemail Folders


6.11.6.3. Mailbox Options
Flowchart of Changing Mailbox Options

Figure 46. Flowchart of Changing Mailbox Options


6.11.6.4. Leaving a Message
Flowchart of Leaving a Voice Message

Figure 47. Flowchart of Leaving a Voice Message


6.12. Configuring Subscriber IVR Language

The language for the Voicemail system IVR or Vertical Service Codes (VSC) IVRs may be set using the subscriber or domain preference language.

Set Subscriber IVR Language

The sip:provider PRO provides the pre-installed prompts for the Voicemail in the English, Spanish, French and Italian languages and the pre-installed prompts for the Vertical Service Codes IVRs in English only.

The other IVRs such as the Conference system and the error announcements use the Sound Sets configured in NGCP Panel and uploaded by the administrator in his language of choice.

6.13. Sound Sets

The sip:provider PRO provides the administrator with ability to upload the voice prompts such as conference prompts or call error announcements on the Sound Sets page. There is a preference sound_set in the NAT and Media Flow Control section on Domain and Subscriber levels to link subscribers to the sound set that they should hear (as usual the subscriber preference overrides the domain one). Sound Sets can be defined in SettingsSound Sets. To create a new Sound Set, click Create Sound Set. Then click the Files button.

Create a Sound Set

info

You may use 8 or 16 bit mono WAV audio files for all of the voice prompts.

6.13.1. Configuring Early Reject Sound Sets

The call error announcements are grouped under Early Rejects section. Unfold the section and click Upload next to the sound handles (Names) that you want to use. Choose a WAV file from your file system, and click the Loopplay setting if you want to play the file in a loop instead of just once. Click Save to upload the file.

Early Reject Sounds

The call error announcements are played to the user in early media hence the name "Early Reject". If you don’t provide the sound files for any handles they will not be used and the sip:provider PRO will fallback to sending the error response code back to the user.

The exact error status code and text are configurable in the /etc/ngcp-config/config.yml file, in kamailio.proxy.early_rejects section. Please look for the announcement handle listed in below table in order to find it in the configuration file.

Table 3. Early Reject Announcements

HandleDescriptionMessage played

announce_before_cf

This is an announcement that the calling party hears before the call is being forwarded (Unconditional and Not Available cases) to the destination. The feature can be activated with Applications / play_announce_before_cf domain or subscriber preference.

N/A (custom message, no default)

block_in

This is what the calling party hears when a call is made from a number that is blocked by the incoming block list (adm_block_in_list, block_in_list customer/subscriber preferences)

Your call is blocked by the number you are trying to reach.

block_out

This is what the calling party hears when a call is made to a number that is blocked by the outgoing block list (adm_block_out_list, block_out_list customer/subscriber preferences)

Your call to the number you are trying to reach is blocked.

block_ncos

This is what the calling party hears when a call is made to a number that is blocked by the NCOS level assigned to the subscriber or domain (the NCOS level chosen in ncos and adm_ncos preferences). PLEASE NOTE: It is not possible to configure the status code and text.

Your call to the number you are trying to reach is not permitted.

block_override_pin_wrong

Announcement played to calling party if it used wrong PIN code to override the outgoing user block list or the NCOS level for this call (the PIN set by block_out_override_pin and adm_block_out_override_pin preferences)

The PIN code you have entered is not correct.

callee_busy

Announcement played on incoming call to the subscriber which is currently busy (486 response from the UAS)

The number you are trying to reach is currently busy. Please try again later.

callee_offline

Announcement played on incoming call to the subscriber which is currently not registered

The number you are trying to reach is currently not available. Please try again later.

callee_tmp_unavailable

Announcement played on incoming call to the subscriber which is currently unavailable (408, other 4xx or no response code or 30x with malformed contact)

The number you are trying to reach is currently not available. Please try again later.

callee_unknown

Announcement that is played on call to unknown or invalid number (not associated with any of our subscribers/hunt groups)

The number you are trying to reach is not in use.

cf_loop

Announcement played when the called subscriber has the call forwarding configured to itself

The number you are trying to reach is forwarded to an invalid destination.

emergency_geo_unavailable

Announcement played when emergency destination is dialed but the destination is not provisioned for the location of the user. PLEASE NOTE: The configuration entry for this case in /etc/ngcp-config/config.yml file is emergency_invalid.

The emergency number you have dialed is not available in your region.

emergency_unsupported

Announcement played when emergency destination is dialed but the emergency calls are administratively prohibited for this user or domain (reject_emergency preference is enabled)

You are not allowed to place emergency calls from this line. Please use a different phone.

error_please_try_later

Announcement played when the call is handled by 3rd party call control (PCC) and there was an error during call processing. PLEASE NOTE: This announcement may be configured in the sound set in voucher_recharge section.

An error has occured. Please try again later.

invalid_speeddial

This is what the calling party hears when it calls an empty speed-dial slot

The speed dial slot you are trying to use is not available.

locked_in

Announcement played on incoming call to a subscriber that is locked for incoming calls

The number you are trying to reach is currently not permitted to receive calls.

locked_out

Announcement played on outgoing call to subscriber that is locked for outgoing calls

You are currently not allowed to place outbound calls.

max_calls_in

Announcement played on incoming call to a subscriber who has exceeded the concurrent_max limit by sum of incoming and outgoing calls or whose customer has exceeded the concurrent_max_per_account limit by sum of incoming and outgoing calls

The number you are trying to reach is currently busy. Please try again later.

max_calls_out

Announcement played on outgoing call to a subscriber who has exceeded the concurrent_max (total limit) or concurrent_max_out (limit on number of outbound calls) or whose customer has exceeded the concurrent_max_per_account or concurrent_max_out_per_account limit

All outgoing lines are currently in use. Please try again later.

max_calls_peer

Announcement played on calls from the peering if that peer has reached the maximum number of concurrent calls (configured by admin in concurrent_max preference of peering server). PLEASE NOTE: There is no configuration option of the status code and text in config.yml file for this case.

The network you are trying to reach is currently busy. Please try again later.

no_credit

Announcement played when prepaid account has insufficient balance to make a call to this destination

You don’t have sufficient credit balance for the number you are trying to reach.

peering_unavailable

Announcement played in case of outgoing off-net call when there is no peering rule matching this destination and/or source

The network you are trying to reach is not available.

reject_vsc

When the VSC (Vertical Service Code) service is disabled in domain or subscriber preferences (Access Restrictions / reject_vsc is set to TRUE) and a subscriber tries to make a call with VSC, an announcement is played.

N/A (custom message, no default)

relaying_denied

Announcement played on inbound call from trusted IP (e.g. external PBX) with non-local Request-URI domain

The network you are trying to reach is not available.

unauth_caller_ip

This is what the calling party hears when it tries to make a call from unauthorized IP address or network (allowed_ips, man_allowed_ips preferences)

You are not allowed to place calls from your current network location.

voicebox_unavailable

PLEASE NOTE: This announcement is already obsolete, as of NGCP version mr5.3

The voicemail of the number you are trying to reach is currently not available. Please try again later.


There are some early reject scenarios when either no voice announcement is played, or a fixed announcement is played. In either case a SIP error status message is sent from NGCP to the calling party. It is possible to configure the exact status code and text for such cases in the /etc/ngcp-config/config.yml file, in kamailio.proxy.early_rejects section. The below table gives an overview of those early reject cases.

Table 4. Additional Early Reject Reason Codes

HandleDescription

block_admin

Caller blocked by adm_block_in_list, adm_block_in_clir and callee blocked by adm_block_out_list (customer or subscriber preference)

block_callee

Callee blocked by subscriber preference block_out_list

block_caller

Caller blocked by subscriber preference block_in_list, block_in_clir

block_contract

Caller blocked by customer preference block_in_list, block_in_clir and callee blocked by customer preference block_out_list

callee_tmp_unavailable_gp

Callee is a PBX group with 0 members. Announcement callee_tmp_unavailable is played; status code and text can be configured.

callee_tmp_unavailable_tm

Callee is a PBX group and we have a timeout (i.e. no group member could be reached). Announcement callee_tmp_unavailable is played; status code and text can be configured.

emergency_invalid

PLEASE NOTE: This handle refers to the same early reject case as emergency_geo_unavailable, but is labeled differently in the configuration file.


6.14. Conference System

The sip:provider PRO provides the simple pin-protected conferencing service built using the SEMS DSM scripting language. Hence it is open for all kinds of modifications and extensions.

Template files for the sems conference scripts stored in /etc/ngcp-config/templates/etc/ngcp-sems/:

  • IVR script: /etc/ngcp-config/templates/etc/ngcp-sems/dsm/confpin.dsm.tt2
  • Config: /etc/ngcp-config/templates/etc/ngcp-sems/dsm/confpin.conf.tt2

6.14.1. Configuring Call Forward to Conference

Go to your Subscriber Preferences and click Edit on the Call Forward Type you want to set (e.g. Call Forward Unconditional).

Configure Call Forward to Conference

You should select Conference option in the Destination field and leave the URI/Number empty. The timeout defines for how long this destination should be tried to ring.

6.14.2. Configuring Conference Sound Sets

Sound Sets can be defined in SettingsSound Sets. To create a new Sound Set, click Create Sound Set. Then click the Files button.

Conference Sounds

Upload the following files:

Table 5. Conference Sound Sets

HandleMessage played

conference_greeting

Welcome to the conferencing service.

conference_pin

Please enter your PIN, followed by the pound key.

conference_pin_wrong

You have entered an invalid PIN number. Please try again.

conference_joined

You will be placed into the conference.

conference_first

You are the first person in the conference.

conference_join

A person has joined the conference.

conference_leave

A person has left the conference.

conference_max_participants

All conference lines are currently in use. Please try again later.

conference_waiting_music

…waiting music…

goodbye

Goodbye.


info

You may use 8 or 16 bit mono WAV audio files.

Then set the preference sound_set on the Domain or Subscriber level in order to assign the Sound Set you have just created to the subscriber (as usual the subscriber preference overrides the domain one).

6.14.3. Joining the Conference

There are 2 ways of joining a conference: with or without PIN code. The actual way of joining the conference depends on Subscriber settings. A subscriber who has activated the conference through call forwarding may set a PIN in order to protect the conference from unauthorized access. To activate the PIN one has to enter a value in Subscriber → Details → Preferences → Internals → conference_pin field.

Setting Conference PIN

Figure 48. Setting Conference PIN


In case the PIN protection for the conference is activated, when someone calls the subscriber who has enabled the conference, the caller is prompted to enter the PIN of the conference. Upon the successful entry of the PIN the caller hears the announcement that he is going to be placed into the conference and at the same time this is announced to all participants already in the conference.

6.14.4. Conference Flowchart with Voice Prompts

The following 2 sections show flowcharts with voice prompts that are played to a caller when he dials the conference.

6.14.4.1. Conference Flowchart with PIN Validation
Flowchart of Conference with PIN Validation

Figure 49. Flowchart of Conference with PIN Validation


6.14.4.2. Conference Flowchart without PIN
Flowchart of Conference without PIN

Figure 50. Flowchart of Conference without PIN


6.15. Malicious Call Identification (MCID)

MCID feature allows customers to report unwanted calls to the platform operator.

6.15.1. Setup

To enable the feature first edit config.yml and enable there apps: malicious_call: yes and kamailio: store_recentcalls: yes. The latter option enables kamailio to store recent calls per subscrbriber UUID in the redis DB (the amount of stored recent calls will not exceed the amount of provisionined subscribers).

Next step is to create a system sound set for the feature. In Settings→Sound Sets either use your already existing Sound Set or create a new Sound Set and then assign it to your domain or subscribers. In the Sound Set there is a fileset malicious_call_identification→mailicious_call_report for that purpose.

Once the Sound Set is created the Subscriber’s Preferences Malicious Call Identification must be enabled under Subcriber → Preferences → Applications menu. The same parameter can be set in the Customer’s preferences to enable this feature for all its subscribers.

The final step is to create a new Rewrite Rule and to route calls to, for instance *123 → MCID application. For that you create a Calee Inbound rewrite rule ^(\*123)$malicious_call

Finaly you run ngcpcfg apply Enabling MCID to recreate the templates and automatically restart depended services.

6.15.2. Usage

As a subscriber, to report a malicious call you call to either malicious_call or to your custom number assigned for that purpose. Please note that you can report only your last received call. You will hear the media reply from the Sound Set you have previosuly configured.

To check reported malicious calls as the plafrom operator open Settings→Malicious Calls tab where you will see a list of registered calls. You can selectively delete records from the list and alternatively you can manage the reported calls by using the REST API.

6.15.3. Advanced configuration

By default the expiration time for the most recent call per subscriber is 3600 seconds (1 hour). If you wish to prolong or shorten the expiration time open constants.yml and set there recentcalls: expire: 3600 to a new value, and issue ngcpcfg apply Enabling MCID afterwards.

6.16. Subscriber Profiles

The preferences a subscriber can provision by himself via the CSC can be limited via profiles within profile sets assigned to subscribers.

6.16.1. Subscriber Profile Sets

Profile sets define containers for profiles. The idea is to define profile sets with different profiles by the administrator (or the reseller, if he is permitted to do so). Then, a subscriber with administrative privileges can re-assign profiles within his profile sets for the subscribers of his customer account.

Profile Sets can be defined in SettingsSubscriber Profiles. To create a new Profile Set, click Create Subscriber Profile Set.

Create Subscriber Profile Set

You need to provide a reseller, name and description.

To create Profiles within a Profile Set, hover over the Profile Set and click the Profiles button.

Profiles within a Profile Set can be created by clicking the Create Subscriber Profile button.

Create Subscriber Profile

Checking the Default Profile option causes this profile to get assigned automatically to all subscribers, who have the profile set assigned. Other options define the user preferences which should be made available to the subscriber.

info

When the platform administrator selects Preferences of the Subscriber Profile he will get an empty page like in the picture below, if none or only certain options are selected in the Subscriber Profile.

Empty Subscriber Profile

Some of the options, like ncos (NCOS level), will enable the definition of that preference within the Subscriber Profile Preferences. Thus all subscribers who have this profile assigned to will have the preference activated by default. The below picture shows the preferences linked to the sample Subscriber Profile:

Subscriber Profile with NCOS Preferences

6.17. SIP Loop Detection

In order to detect a SIP loop ( incoming call as a response for a call request ) sip:provider PRO checks the combination of SIP-URI, To and From headers.

This check can be enabled in config.yml by setting kamailio.proxy.loop_detection.enable: 'yes'. The system tolerates kamailio.proxy.loop_detection.max loops within kamailio.proxy.loop_detection.expire seconds. Higher occurrence of loops will be reported with a SIP 482 "Loop Detected" error message

6.18. Call-Through Application

Call-through allows telephony client to dial into an IVR system and specify (in two-stage dialing fashion) a new destination number which is then dialed by the sip:provider PRO to connect the client to the destination. As the call-through system needs to be protected from unauthorized use, a list of CLIs which are allowed to use the call-through system is stored in the sip:provider PRO platform.

Table 6. Call-Through Mappings

ColumnDescription

uuid

The internal UUID of the call-through subscriber

auth_key

Authentication key (CLI)

source_uuid

The internal UUID of the subscriber that is authorized for outgoing call leg (same as uuid in call-through scenario)


6.18.1. Administrative Configuration

6.18.1.1. Subscriber provisioning

In order to manage the call-through CLIs for subscriber, navigate to SettingsSubscribers, search for the subscriber you want to edit, press Details and then Preferences, scroll down to the Callthrough CLIs section and press Edit Callthrough CLIs button.

Subscriber Callthrough CLIs

Using the NGCP Panel the user then creates Call Forward to destination Call Through.

6.18.1.2. Forward to local user

If the subscriber has a Call Forward to the call-through application but caller’s CLI is not in the authorized CLIs list for call-through, sems responds with error back to proxy and proxy advances to the next number in the Call Forward destinations set. User can enter special destination Local Subscriber as next target after Call Through in the destinations set in order to terminate the call to the subscriber as if the subscriber didn’t exist. This way the user may reach the call-through application from his authorized CLI (e.g. mobile number) and all other callers would reach the SIP subscriber’s registered phone as usual.

Forward to Callthrough application

6.18.1.3. Sound Set provisioning

In order for the Callthrough application to work a Sound Set must be created and associated with the Domain or Subscriber.

Sound Sets can be defined in SettingsSound Sets. To create a new Sound Set, click Create Sound Set. Then click the Files button. Administrator can upload the default sounds in one of supported languages or uploaded by the administrator manually in his language of choice.

There is a preference sound_set on Domain and Subscriber levels to link subscribers to the sound set that they should hear (as usual the subscriber preference overrides the domain one).

Create a Sound Set

info

You may use 8 or 16 bit mono WAV audio files for all of the voice prompts.

6.18.2. Call Flow

The call arrives at sems application server with Request-URI user callthrough.

6.18.2.1. Internal Header Parameters

The INVITE contains an extra SIP header P-App-Param with the following parameters:

Table 7. SIP Header parameters for call-through application

NameMeaning

uuid

The internal UUID of the call-through subscriber

srcnumber

Caller’s CLI for the authentication

outgoing_cli

New CLI to be used by sems application for the outgoing call leg


6.18.2.2. Caller authorization

Caller is authorized using mapping shown in table above: select source_uuid from provisioning.voip_cc_mapping where uuid=$uuid and auth_key=$srcnumber;

If the check fails return the configured error response code. Then proceed with the call setup as follows.

6.18.2.3. Outgoing call

Sems requests the user to enter destination and starts digit collection. Digit collection process is terminated after 5 seconds (configurable in sems config file) or by pressing the # key. User can start entering destination while the voice prompt is being played.

Sems sends INVITE to the proxy with Request-URI: sip:$number@$outboundproxy;sw_domain=$subscriber.domain

From: $outgoing_cli

On receiving the 401 or 407 response from the proxy the application authenticates using the digest credentials retrieved for the call-through subscriber from the voip_subscribers table:select s.username, s.password, d.domain from provisioning.voip_subscribers s, provisioning.voip_domains d where s.uuid=$source_uuid and s.domain_id=d.id;

If the call setup fails the application plays back the "could_not_connect" sound file. If successful the application acts transparently and does not provide any voice announcements or DTMF detection.

6.18.2.4. CLI configuration

The CLI on the outgoing call from the call-through module is set to the Network-Provided Number (NPN) of the call-through subscriber. There is nothing to configure.

6.19. Calling Card Application

Calling card application uses a similar concept to call-through except that authorization process operates on the PIN code entered by user using DTMF instead of the CLI. The sip:provider PRO maps incoming UUID of the pilot subscriber to the list of PINs for calling card application with their corresponding subscriber UUIDs for outbound call leg using table provisioning.voip_cc_mapping table {"uuid", "auth_key", "source_uuid"}

Table 8. Calling Cards

ColumnDescription

uuid

The internal UUID of the pilot subscriber

auth_key

Authentication key (PIN)

source_uuid

The internal UUID of the subscriber that is authorized for outgoing call leg


6.19.1. Administrative Configuration

6.19.1.1. Subscriber provisioning

In order to use the calling cards service the user creates a Call Forward to destination Calling Card for the designated subscriber that will be used as access number for this service.

6.19.1.2. Sound Set provisioning

In order for the Calling Card application to work a Sound Set must be created and associated with the Domain or Subscriber.

Sound Sets can be defined in SettingsSound Sets. To create a new Sound Set, click Create Sound Set. Then click the Files button. Administrator can upload the default sounds in one of supported languages or uploaded by the administrator manually in his language of choice.

There is a preference sound_set on Domain and Subscriber levels to link subscribers to the sound set that they should hear (as usual the subscriber preference overrides the domain one).

Create a Sound Set

info

You may use 8 or 16 bit mono WAV audio files for all of the voice prompts.

6.19.1.3. CLI configuration

The CLI on the outgoing call from the calling card app can be configured in one of the following ways using subscriber preferences:

1) Show original caller’s CLI: the calling card subscriber shall have allowed_clis: * (any). Sems application sends the original caller’s CLI in the From header, it is validated by the SIP proxy and sent to outside.

2) Show number of the pilot (calling card) subscriber: the calling card subscriber shall have an empty allowed_clis and desired number set as value of user_cli preference. The SIP proxy overrides the original caller’s CLI in UPN with the value of the user_cli preference. The peer must have set outbound_from_user, outbound_from_display: User-Provided Number (UPN).

6.19.2. Call Flow

The call arrives at sems application server with Request-URI user callingcard.

6.19.2.1. Internal Header Parameters

The INVITE contains an extra SIP header P-App-Param with the following parameters:

Table 9. SIP Header parameters for calling card application

NameMeaning

uuid

The internal UUID of the pilot subscriber

outgoing_cli

New CLI to be used by sems application for the outgoing call leg


6.19.2.2. Caller authorization
  • Sems requests the user to enter PIN and starts digit collection. Digit collection process is terminated after 5 seconds (configurable in sems config file) or by pressing the # key. User can start entering destination while the voice prompt is being played.
  • Sems checks that PIN is valid and belongs to the pilot subscriber using mapping as shown in the table. It fetches UUID of the subscriber to be used for outgoing call leg: select source_uuid from provisioning.voip_cc_mapping where uuid=$uuid and auth_key=$pin;
  • If the check fails sems will request the user to re-enter PIN up to the configured number of times.
  • If successful proceed with the call setup making call on behalf of subscriber determined by the source_uuid key as follows.
6.19.2.3. Outgoing call

Sems application plays back the available balance of the customer. Sems requests the user to enter destination and starts digit collection. Digit collection process is terminated after 5 seconds (configurable in sems config file) or by pressing the # key. User can start entering destination while the voice prompt is being played.

Sems sends INVITE to the proxy with Request-URI: sip:$number@$outboundproxy;sw_domain=$subscriber.domain

From: $outgoing_cli

On receiving the 401 or 407 response from the proxy the application authenticates using the digest credentials retrieved for the subscriber for outgoing call leg from the voip_subscribers table: select s.username, s.password, d.domain from provisioning.voip_subscribers s, provisioning.voip_domains d where s.uuid=$source_uuid and s.domain_id=d.id;

6.19.2.4. Voucher recharge

During the destination collection phase in calling card application user can enter special code *1*<pin># (configurable in sems config file) to transfer balance from other calling card customer to the currently authorized customer. Sems transfers all remaining balance from that customer to the current customer.

6.19.2.5. Billing

The call via calling card application as well as call-through generates three CDRs:

  • A to B: The incoming call from any source to the call-through subscriber.
  • B to callingcard@app.local or callthrough@app.local: The call forward to the sems application.
  • B to C: The outgoing call to the final destination. The three CDRs are handled by the billing process as usual, exported and shown in all call lists. .

6.20. Invoices and Invoice Templates

Content and vision of the invoices are customizable by invoice templates Section 6.20.2, “Invoice Templates”.

info

The sip:provider PRO generates invoices in pdf format.

6.20.1. Invoices Management

Invoices can be requested for generation, searched, downloaded and deleted in the invoices interface.

Invoice management interface

To request invoice generation for the particular customer and period press "Create invoice" button. On the invoice creation form following parameters are available for selection:

  • Template: any of existent invoice template can be selected for the invoice generation.
  • Customer: owner of the billing account, recipient of the invoice.
  • Invoice period: billing period. Can be specified only as one calendar month. Calls with start time between first and last second of the period will be considered for the invoice

All form fields are mandatory.

Invoice creation form

Generated invoice can be downloaded as pdf file.

Invoice created view

To do it press button "Download" against invoice in the invoice management interface.

Respectively press on the button "Delete" to delete invoice.

6.20.2. Invoice Templates

Invoice template defines structure and look of the generated invoices. The sip:provider PRO makes it possible to create some invoice templates. Multiple invoice templates can be used to send invoices to the different customers using different languages.

important

At least one invoice template should be created to enable invoice generation. Each customer has to be associated to one of the existent invoice template, otherwise invoices will be not generated for this customer.

Customer can be linked to the invoice template in the customer interface.

6.20.2.1. Invoice Templates Management

Invoice templates can be searched, created, edited and deleted in the invoice templates management interface.

Invoice templates management interface

Invoice template creation is separated on two steps:

  • Register new invoice template meta information.
  • Edit content (template itself) of the invoice template.

To register new invoice template press "Create Invoice Template" button.

On the invoice template meta information form following parameters can be specified:

  • Reseller: reseller who owns this invoice template. Please note, that it doesn’t mean that the template will be used for the reseller customers by default. After creation, invoice template still need to be linked to the reseller customers.
  • Name: unique invoice template name to differentiate invoice templates if there are some.
  • Type: currently sip:provider PRO supports only svg format of the invoice templates.

All form fields are mandatory.

Invoice template creation form

After registering new invoice template you can change invoice template structure in WYSIWYG SVG editor and preview result of the invoice generation based on the template.

6.20.2.2. Invoice Template Content

Invoice template is a XML SVG source, which describes content, look and position of the text lines, images or other invoice template elements. The sip:provider PRO provides embedded WYSIWYG SVG editor svg-edit 2.6 to customize default template. The sip:provider PRO svg-edit has some changes in layers management, image edit, user interface, but this basic introduction still may be useful.

Template refers to the owner reseller contact ("rescontact"), customer contract ("customer"), customer contact ("custcontact"), billing profile ("billprof"), invoice ("invoice") data as variables in the "[%%]" mark-up with detailed information accessed as field name after point e.g. [%invoice.serial%]. During invoice generation all variables or other special tokens in the "[% %]" mark-ups will be replaced by their database values.

Press on "Show variables" button on invoice template content page to see full list of variables with the fields:

Invoice template available variables

You can add/change/remove embedded variables references directly in main svg-edit window. To edit text line in svg-edit main window double click on the text and place cursor on desired position in the text.

After implementation of the desired template changes, invoice template should be saved Section 6.20.2.3, “Save and preview invoice template content”.

To return to the sip:provider PRO invoice template default content you can press on the "Discard changes" button.

important

"Discard changes" operation can’t be undone.

Layers

Default template contains three groups elements (<g/>), which can be thinked of as pages, or in terms of svg-edit - layers. Layers are:

  • Background: special layer, which will be repeated as background for every other page of the invoice.
  • Summary: page with a invoice summary.
  • CallList: page with calls made in a invoice period. Is invisible by default.

To see all invoice template layers, press on "Layers" vertical sign on right side of the svg-edit interface:

Invoice template layers

Side panel with layers list will be shown.

Invoice template layers open

One of the layers is active, and its element can be edited in the main svg-edit window. Currently active layer’s name is bold in the layers list. The layers may be visible or invisible. Visible layers have "eye" icon left of their names in the layers list.

To make a layer active, click on its name in the layers list. If the layer was invisible, its elements became visible on activation. Thus you can see mixed elements of some layers, then you can switch off visibility of other layers by click on their "eye" icons. It is good idea to keep visibility of the "Background" layer on, so look of the generated page will be seen.

Edit SVG XML source

Sometimes it may be convenient to edit svg source directly and svg-edit makes it possible to do it. After press on the <svg> icon in the top left corner of the svg-edit interface:

Invoice xml source button

SVG XML source of the invoice template will be shown.

SVG source can be edited in place or just copy-pasted as usual text.

info

Template keeps sizes and distances in pixels.

important

When edit svg xml source, please change very carefully and thinkfully things inside special comment mark-up "<!--{ }-→". Otherwise invoice generation may be broken. Please be sure that document structure repeats default invoice template: has the same groups (<g/>) elements on the top level, text inside special comments mark-up "<!--{ }-→" preserved or changed appropriately, svg xml structure is correct.

To save your changes in the svg xml source, first press "OK" button on the top left corner of the source page:

Save xml source changes

And then save invoice template changes Section 6.20.2.3, “Save and preview invoice template content”.

info

You can copy and keep the svg source of your template as a file on the disk before start experimenting with the template. Later you will be able to return to this version replacing svg source.

Change logo image

  • Make sure that "Select tool" is active.
  • Select default logo, clicking on the logo image.
  • Press "Change image" button, which should appear on the top toolbar.

Steps to change the image

After image uploaded save invoice template changes Section 6.20.2.3, “Save and preview invoice template content”.

6.20.2.3. Save and preview invoice template content

To save invoice template content changes press button "Save SVG".

Save invoice template

You will see message about successfully saved template. You can preview your invoice look in PDF format. Press on "Preview as PDF" button.

Preview invoice template

Invoice preview will be opened in the new window.

info

Example fake data will be used for preview generation.

Preview invoice as PDF

6.20.3. Invoices Generation

Besides generating invoices on demand using web interface, Sipwise NGCP contains an invoice generator script that allows for producing invoices automatically, at regular intervals, for all customers, using the cron system tool.

warning

Automated invoice generation is deprecated since mr4.0 release of NGCP. The invoice generator script will damage billing records in the database. The rest of the description in "Invoices Generation" section is kept in the handbook for reference purposes only.

Script is located at: /usr/share/ngcp-panel/tools/generate_invoices.pl

In short:

  • To generate and immediately send invoices for the previous month:
perl /usr/share/ngcp-panel/tools/generate_invoices.pl --send --prevmonth
  • To generate invoices for the previous month without sending:
perl /usr/share/ngcp-panel/tools/generate_invoices.pl --prevmonth
  • To send already generated invoices for the previous month:
perl /usr/share/ngcp-panel/tools/generate_invoices.pl --sendonly --prevmonth
  • Regenerate invoices for the specified period:
perl /usr/share/ngcp-panel/tools/generate_invoices.pl --stime="2015-01-01 00:00:00"  --etime="2015-01-31 00:00:00" --regenerate

Some not obvious options:

  • *--allow_terminated* Generates invoices for the terminated contracts too.
  • *--force_unrated* Generate invoices despite unrated calls existence in the specified generation period.
  • *--no_empty* Skip invoices for the contracts without calls in the specified period and with null permanent fee for the billing profile.

To see all possible script options use --help or --man:

/usr/share/ngcp-panel/tools/generate_invoices.pl --man

Script will be run periodically as configured by the cron files. Cron files templates can be found at:

  • /etc/ngcp-config/templates/etc/cron.d/ngcp-invoice-gen.tt2
  • /etc/ngcp-config/templates/etc/cron.d/ngcp-invoice-gen.services

After applying your configuration cron file will be located at:

  • /etc/cron.d/ngcp-invoice-gen

Script uses configuration file located at: /etc/ngcp-invoice-gen/invoice-gen.conf

Except common DB connection configuration following specific options can be defined in the config file:

  • RESELLER_ID 1,2,3,…N

Comma separated resellers id. Invoice generation will be performed only for the specified resellers.

  • CLIENT_CONTRACT_ID 1,2,3,…N

Comma separated customers id. Invoice generation will be performed only for the specified customers.

  • STIME YYYY-mm-DD HH:MM:SS

Usually is not necessary. Script option --prevmonth will define correct start and end time for the previous month billing period. Generated invoices will include all calls with call start time more then STIME value and less the ETIME value.

  • ETIME YYYY-mm-DD HH:MM:SS

Usually is not necessary. Script option --prevmonth will define correct start and end time for the previous month billing period. Generated invoices will include all calls with call start time more then STIME value and less the ETIME value.

  • SEND [0|1]

Generated invoices will be immediately sent to the customers.

  • RESEND [0|1]

Invoices, already sent to the customers, will be sent again.

  • REGENERATE [0|1]

Already presented invoices files will be generated again. Otherwise they will stay intouched.

  • ALLOW_TERMINATED [0|1]

Generate invoices for the already terminated customers too.

  • ADMIN_EMAIL your@email.com

Purposed for notifications about invoices generation fails. Not in use now.

All generated invoices can be seen in the invoice management interface Section 6.20.1, “Invoices Management”.

On request each invoice will be sent to the proper customer as e-mail with the invoice PDF in the attachment. Letter content is defined by the invoice email template.

6.21. Email Reports and Notifications

6.21.1. Email events

The sip:provider PRO makes it possible to customize content of the emails sent on the following actions:

  • Web password reset requested. Email will be sent to the subscriber, whom password was requested for resetting. If the subscriber doesn’t have own email, letter will be sent to the customer, who owns the subscriber.
  • New subscriber created. Email will be sent to the newly created subscriber or to the customer, who owns new subscriber.
  • Letter with the invoice. Letter will be sent to the customer.

6.21.2. Initial template values and template variables

Default email templates for each of the email events are inserted on the initial sip:provider PRO database creation. Content of the default template is described in the corresponding sections. Default email templates aren’t linked to any reseller and can’t be changed through sip:provider PRO Panel. They will be used to initialize default templates for the newly created reseller.

Each email template refers to the values from the database using special mark-ups "[%" and "%]". Each email template has fixed set of the variables. Variables can’t be added or changed without changes in the sip:provider PRO Panel code.

6.21.3. Password reset email template

Email will be sent after subscriber or subscriber administrator requested password reset for the subscriber account. Letter will be sent to the subscriber. If subscriber doesn’t have own email, letter will be sent to the customer owning the subscriber.

Default content of the password reset email template is:

Template name

passreset_default_email

From

default@sipwise.com

Subject

Password reset email

Body

Dear Customer,

Please go to [%url%] to set your password and log into your self-care interface.

Your faithful Sipwise system

--
This is an automatically generated message. Do not reply.

Following variables will be provided to the email template:

  • [%url%]: specially generated url where subscriber can define his new password.
  • [%subscriber%]: username@domain of the subscriber, which password was requested for reset.

6.21.4. New subscriber notification email template

Email will be sent on the new subscriber creation. Letter will be sent to the newly created subscriber if it has an email. Otherwise, letter will be sent to the customer who owns the subscriber.

info

By default email content template is addressed to the customer. Please consider this when create the subscriber with an email.

Template name

subscriber_default_email

From

default@sipwise.com

Subject

Subscriber created

Body

Dear Customer,

A new subscriber [%subscriber%] has been created for you.

Your faithful Sipwise system

--
This is an automatically generated message. Do not reply.

Following variables will be provided to the email template:

  • [%url%]: specially generated url where subscriber can define his new password.
  • [%subscriber%]: username@domain of the subscriber, which password was requested for reset.

6.21.5. Invoice email template

Template name

invoice_default_email

From

default@sipwise.com

Subject

Invoice #[%invoice.serial%] from [%invoice.period_start_obj.ymd%] to [%invoice.period_end_obj.ymd%]

Body

Dear Customer,

Please find your invoice #[%invoice.serial%] for [%invoice.period_start_obj.month_name%], [%invoice.period_start_obj.year%] in attachment of this letter.

Your faithful Sipwise system

--
This is an automatically generated message. Do not reply.

Variables passed to the email template:

  • [%invoice%]: container variable for the invoice information.
infoInvoice fields
  • [%invoice.serial%]
  • [%invoice.amount_net%]
  • [%invoice.amount_vat%]
  • [%invoice.amount_total%]
  • [%invoice.period_start_obj%]
  • [%invoice.period_end_obj%]

The fields [%invoice.period_start_obj%] and [%invoice.period_end_obj%] provide methods of the perl package DateTime for the invoice start date and end date. Further information about DateTime can be obtained from the package documentation:

man DateTime

  • [%provider%]: container variable for the reseller contact. All database contact values will be available.
  • [%client%]: container variable for the customer contact.
infoContact fields example for the "provider". Replace "provider" to client to access proper "customer" contact fields.
  • [%provider.gender%]
  • [%provider.firstname%]
  • [%provider.lastname%]
  • [%provider.comregnum%]
  • [%provider.company%]
  • [%provider.street%]
  • [%provider.postcode%]
  • [%provider.city%]
  • [%provider.country%]
  • [%provider.phonenumber%]
  • [%provider.mobilenumber%]
  • [%provider.email%]
  • [%provider.newsletter%]
  • [%provider.faxnumber%]
  • [%provider.iban%]
  • [%provider.bic%]
  • [%provider.vatnum%]
  • [%provider.bankname%]
  • [%provider.gpp0 - provider.gpp9%]

6.21.6. Email templates management

Email templates linked to the resellers can be customized in the email templates management interface. For the administrative account email templates of all the resellers will be shown. Respectively for the reseller account only owned email templates will be shown.

Email templates management interface

To create create new email template press button "Create Email Template".

Email templates form

On the email template form all fields are mandatory:

  • Reseller: reseller who owns this email template.
  • Name: currently only email template with the following names will be considered by the sip:provider PRO on the appropriate event Section 6.21.1, “Email events” :

    • passreset_default_email;
    • subscriber_default_email;
    • invoice_default_email;
  • From Email Address: email address which will be used in the From field in the letter sent by the sip:provider PRO.
  • Subject: Template of the email subject. Subject will be processed with the same template variables as the email body.
  • Body: Email text template. Will be processed with appropriate template variables.

6.22. The Vertical Service Code Interface

Vertical Service Codes (VSC) are codes a user can dial on his phone to provision specific features for his subscriber account. The format is *<code>*<value> to activate a specific feature, and #<code> or #<code># to deactivate it. The code parameter is a two-digit code, e.g. 72. The value parameter is the value being set for the corresponding feature.

important

The value user input is normalized using the Rewrite Rules Sets assigned to domain as described in Section 5.7, “Configuring Rewrite Rule Sets”.

By default, the following codes are configured for setting features. The examples below assume that there is a domain rewrite rule normalizing the number format 0<ac><sn> to <cc><ac><sn> using 43 as country code.

  • 72 - enable Call Forward Unconditional e.g. to 431000 by dialing *72*01000, and disable it by dialing #72.
  • 90 - enable Call Forward on Busy e.g. to 431000 by dialing *90*01000, and disable it by dialing #90.
  • 92 - enable Call Forward on Timeout e.g. after 30 seconds of ringing to 431000 by dialing *92*30*01000, and disable it by dialing #92.
  • 93 - enable Call Forward on Not Available e.g. to 431000 by dialing *93*01000, and disable it by dialing #93.
  • 50 - set Speed Dial Slot, e.g. set slot 1 to 431000 by dialing *50*101000, which then can be used by dialing *1.
  • 55 - set One-Shot Reminder Call e.g. to 08:30 by dialing *55*0830.
  • 31 - set Calling Line Identification Restriction for one call, e.g. to call 431000 anonymously dial *31*01000.
  • 32 - enable Block Incoming Anonymous Calls by dialing *32*, and disable it by dialing #32.
  • 80 - call using Call Block Override PIN, number should be prefixed with a block override PIN configured in admin panel to disable the outgoing user/admin block list and NCOS level for a call. For example, when override PIN is set to 7890, dial *80*789001000 to call 431000 bypassing block lists.

6.22.1. Vertical Service Codes for PBX customers

Subscribers under the same PBX customer can enjoy some PBX-specific features by means of special VSCs.

NGCP provides the following PBX-specific VSCs:

  • 97 - Call Parking: during a conversation the subscriber can park the call with his phone to a "parking slot" and later on continue the conversation from another phone. To do that, a destination must be dialled as follows: *97*3; this will park the call to slot no. 3.

    PLEASE NOTE:

    • Cisco IP phones provide a softkey for Call Parking, that means the subscriber must only dial the parking slot number after pressing "Park" softkey on the phone.
    • Other IP phones can perform Call Parking as a blind transfer, where the destination of the transfer must be dialled in the format described above.
    • Both the caller and the callee can park the call.
  • 98 - Call Unparking: if a call has been parked, a subscriber may continue the conversation from any extension (phone) under the same PBX customer. To do that, the subscriber must dial the following sequence: *98*3; this will pick up the call that was parked at slot no. 3.
  • 99 - Directed Call Pickup: if a subscriber’s phone is ringing (e.g. extension 23) and another subscriber wants to answer the call instead of the original callee, he may pick up the call by dialling *99*23 on his phone.

6.22.2. Configuration of Vertical Service Codes

You can change any of the codes (but not the format) in /etc/ngcp-config/config.yml in the section semsvsc. After the changes, execute ngcpcfg apply 'changed VSC codes'.

caution

If you have the EMTAs under your control, make sure that the specified VSCs don’t overlap with EMTA-internal VSCs, because the VSC calls must be sent to the NGCP via SIP like normal telephone calls.

6.22.3. Voice Prompts for Vertical Service Code Configuration

Table 10. VSC Voice Prompts

Prompt Handle Related VSC Message

vsc_error

any

An error has occurred. Please try again later.

vsc_invalid

wrong code

Invalid feature code.

reject_vsc

any

Vertical service codes are disabled for this line.

vsc_cfu_on

72 (Call Forward Unconditional)

Your unconditional call forward has successfully been activated.

vsc_cfu_off

72 (Call Forward Unconditional)

Your unconditional call forward has successfully been deactivated.

vsc_cfb_on

90 (Call Forward Busy)

Your call forward on busy has successfully been activated.

vsc_cfb_off

90 (Call Forward Busy)

Your call forward on busy has successfully been deactivated.

vsc_cft_on

92 (Call Forward on Timeout)

Your call forward on ring timeout has successfully been activated.

vsc_cft_off

92 (Call Forward on Timeout)

Your call forward on ring timeout has successfully been deactivated.

vsc_cfna_on

93 (Call Forward on Not Available)

Your call forward while not reachable has successfully been activated.

vsc_cfna_off

93 (Call Forward on Not Available)

Your call forward while not reachable has successfully been deactivated.

vsc_speeddial

50 (Speed Dial Slot)

Your speed dial slot has successfully been stored.

vsc_reminder_on

55 (One-Shot Reminder Call)

Your reminder has successfully been activated.

vsc_reminder_off

55 (One-Shot Reminder Call)

Your reminder has successfully been deactivated.

vsc_blockinclir_on

32 (Block Incoming Anonymous Calls)

Your rejection of anonymous calls has successfully been activated.

vsc_blockinclir_off

32 (Block Incoming Anonymous Calls)

Your rejection of anonymous calls has successfully been deactivated.


6.23. Handling WebRTC Clients

WebRTC is an open project providing browsers and mobile applications with Real-Time Communications (RTC) capabilities. Configuring your platform to offer WebRTC is quite easy and straightforward. This allows you to have a SIP-WebRTC bridge in place and make audio/video call towards normal SIP users from WebRTC clients and vice versa. Sip Provider listens, by default, on the following WebSockets and WebSocket Secure: ws://your-ip:5060/ws, wss://your-ip:5061/ws and wss://your-ip:1443/wss/sip/.

The WebRTC subscriber is just a normal subscriber which has just a different configuration in his Preferences. You need to change the following preferences under Subscribers→Details→Preferences→NAT and Media Flow Control:

  • use_rtpproxy: Always with rtpproxy as additional ICE candidate
  • transport_protocol: RTP/SAVPF (encrypted SRTP with RTCP feedback)

The transport_protocol setting may change, depending on your WebRTC client/browser configuration. Supported protocols are the following:

  • Transparent (Pass through using the client’s transport protocol)
  • RTP/AVP (Plain RTP)
  • RTP/SAVP (encrypted SRTP)
  • RTP/AVPF (RTP with RTCP feedback)
  • RTP/SAVPF (encrypted SRTP with RTCP feedback)
  • UDP/TLS/RTP/SAVP (Encrypted SRTP using DTLS)
  • UDP/TLS/RTP/SAVPF (Encrypted SRTP using DTLS with RTCP feedback)
warning

The below configuration is enough to handle a WebRTC client/browser. As mentioned, you may need to tune a little bit your transport_protocol configuration, depending on your client/browser settings.

In order to have a bridge between normal SIP clients (using plain RTP for example) and WebRTC client, the normal SIP clients' preferences have to have the following configuration:

transport_protocol: RTP/AVP (Plain RTP)

This will teach Sip Provider to translate between Plain RTP and RTP/SAVPF when you have calls between normal SIP clients and WebRTC clients.

6.24. XMPP and Instant Messaging

Instant Messaging (IM) based on XMPP comes with sip:provider PRO out of the box. sip:provider PRO uses prosody as internal XMPP server. Each subscriber created on the platform have assigned a XMPP user, reachable already - out of the box - by using the same SIP credentials. You can easily open an XMPP client (e.g. Pidgin) and login with your SIP username@domain and your SIP password. Then, using the XMPP client options, you can create your buddy list by adding your buddies in the format user@domain.

6.25. Call Recording

6.25.1. Introduction to Call Recording Function

Sipwise NGCP provides an opportunity to record call media content and store that in files. This function is available since mr5.3.1 version of the sip:provider PRO.

Some characteristics of the Call Recording:

  • Call Recording function can store both unidirectional (originating either from caller, or from callee) or bidirectional (combined) streams from calls, resulting in 1, 2 or 3 physical files as output
  • The location and format of the files is configurable.
  • File storage is planned to occur on an NFS shared folder.
  • Activation of call recording may happen generally for a Domain / Peer / Subscriber through the NGCP admin web interface.

    important

    NGCP’s Call Recording function is not meant for individual call interception purpose! Sipwise provides its Lawful Interception solution for that use case.

  • Querying or deletion of existing recordings may happen through the REST API.
  • Listing recordings of a subscriber is possible on NGCP’s admin web interface.

The Call Recording function is implemented using NGCP’s rtpengine module.

info

There are 2 rtpengine daemons employed when call recording is enabled and active. The main rtpengine takes care of forwarding media packets between caller and callee, as usual, while the secondary rtpengine (recording) daemon is responsible for storing call data streams in the file system.

Call Recording is disabled by default. Enabling and configuration of Call Recording takes place in 2 steps:

  1. Enabling the feature on the NGCP by setting configuration parameters in the main config.yml configuration file.
  2. Activating the feature for a Domain / Peer / Subscriber.

6.25.2. Information on Files and Directories

NGCP’s Call Recording function uses an NFS shared folder to save recorded streams.

important

Since call data amount may be huge (depending, of course, on the number and duration of calls), it is strongly not recommended to store recorded streams on NGCP’s local disks. However if you have to store recorded streams as files in the local filesystem, please contact Sipwise Support team in order to get the proper configuration of Call Recording function.

The NFS share gets mounted during startup of the recording daemon. If the NFS share cannot be mounted for some reason, the recording daemon will not start.

Filenames have the format: <call_ID>-<random>-<SSRC>.<extension>, where:

  • call_ID: SIP Call-ID of the call being recorded
  • random: is a string of random characters, unique for each recorded call. It’s purpose is to avoid possible filename collisions if a Call-ID ever gets reused.
  • SSRC: is the RTP SSRC for unidirectional recordings, or “mix” for the bidirectional (combined) audio.
  • extension: is either “mp3” or “wav”, depending on the configuration (rtpproxy.recording.output_format)

There might be 1, 2 or 3 files produced as recorded streams. The number of files depends on the configuration:

  1. rtpproxy.recording.output_mixed = ‘yes’ (combined stream required)

    rtpproxy.recording.output_single = ‘no’ (unidirectional streams not required)

  2. rtpproxy.recording.output_mixed = ‘no’ (combined stream not required)

    rtpproxy.recording.output_single = ‘yes’ (unidirectional streams required)

  3. rtpproxy.recording.output_mixed = ‘yes’ (combined stream required)

    rtpproxy.recording.output_single = ‘yes’ (unidirectional streams required)

6.25.3. Configuration

The Call Recording function can be enabled and configured on the NGCP by changing the following configuration parameters in config.yml file:

rtpproxy:
  ...
  recording:
    enabled: no
    mp3_bitrate: '48000'
    nfs_host: 192.168.1.1
    nfs_remote_path: /var/recordings
    output_dir: /var/lib/rtpengine-recording
    output_format: wav
    output_mixed: yes
    output_single: yes
    resample: no
    resample_to: '16000'
    spool_dir: /var/spool/rtpengine
6.25.3.1. Enabling Call Recording

Enabling the function requires changing the value of rtpproxy.recording.enabled parameter to “yes”. In order to make the new configuration active, it’s necessary to do:

ngcpcfg apply ‘Activated call recording’

Description of configuration parameters:

  • enabled: when set to “yes” Call Recording function is enabled; default: “no”
  • mp3_bitrate: the bitrate used when recording happens in MP3 format; default: "48000"
  • nfs_host: IP address of the NFS host that provides storage space for recorded streams; default: "192.168.1.1"
  • nfs_remote_path: the remote path (folder) where files of recorded streams are stored on the NFS share; default: "/var/recordings"
  • output_dir: is the local mount point for the NFS share, and thus where the final audio files will be written; default: "/var/lib/rtpengine-recording"

    caution

    Normally you don’t need to change the default setting. If you do change the value, please be aware that recorded files will be written by root user in that directory.

  • output_format: possible values are “wav” (Wave) or “mp3” (MP3); default: “wav”
  • output_mixed: “yes” means that there is a file that contains a mixed stream of caller and callee voice data; default: "yes"
  • output_single: “yes” means that there is a separate file for each stream direction, i.e. for the streams originating from caller and callee; default: "yes"
  • resample: when set to “yes” the call data stream will be resampled before storing it in the file; default: “no”
  • resample_to: the sample rate used for resampling output; default: "16000"
  • spool_dir: is the place for temporary metadata files that are used by the recording daemon and the main rtpengine daemon for their communication; default: "/var/spool/rtpengine"

    caution

    You should not change the default setting unless you have a good reason to do so! Sipwise has thoroughly tested the Call Recording function with the default setting.

If Call Recording is enabled you can see 2 rtpengine processes running when checking the NGCP system state with monit tool:

root@sp1:/etc/ngcp-config# monit summary
...
Process 'lb'                        Running
Process 'rtpengine'                 Running
Process 'rtpengine-recording'       Running
Process 'voisniff-ng'               Running
...
6.25.3.2. Activating Call Recording

Activating Call Recording for e.g. a Subscriber: please use NGCP’s admin web interface for this purpose. On the web interface one has to navigate as follows: Settings → Subscribers → select subscriber Details → Preferences → NAT and Media Flow Control. Afterwards the record_call option has to be enabled by pressing the Edit button and ticking the checkbox.

Activating Call Recording

Figure 51. Activating Call Recording


info

The call recording function may be activated for a single Subscriber, a Domain and a Peer server in the same way: Preferences → NAT and Media Flow Control → record_call. When activating call recording for a Domain or Peer this effectively activates the function for all subscribers that belong to the selected domain, and for all calls with a local endpoint going through the selected peer server, respectively.

It is possible to list existing call recordings of a Subscriber through the admin web interface of NGCP. In order to do so, please navigate to: Settings → Subscribers → select subscriber Details → Call Recordings

Listing Call Recordings

Figure 52. Listing Call Recordings


If you select an item in the list, besides the main properties such as the time of call and the SIP Call-ID, you can retrieve the details of the related call (press the Call Details button), get the list of recorded files (press the Recorded Files button) or Delete the recorded call.

When selecting Call Details you will see the most important accounting data of the call. Furthermore you can see the SIP Call Flow or the complete Call Details if you press the respective buttons.

Listing Call Details for a Recording

Figure 53. Listing Call Details for a Recording


When navigating to Recorded Files of a call you will be presented with a list of files. For each file item:

  • type of stream is shown, that can be either "mixed" (combined voice data), or "single" (voice data of caller or callee)
  • file format is shown, that can be either "wav", or "mp3"
  • you can download the file by pressing the Play button
Listing Files for a Recording

Figure 54. Listing Files for a Recording


6.25.4. REST API

The NGCP REST API provides methods for querying and deletion of existing recording data. The full documentation of the available API methods is available on the admin web interface of the NGCP, as usual.

The following API methods are provided for managing Call Recordings:

  • CallRecordings:

    • Provides information about the calls recorded in the system; can also be used to delete a recording entry
    • accessible by the path: /api/callrecordings (collection) or /api/callrecordings/id (single item)
    • Supported HTTP methods: OPTIONS, GET, DELETE
  • CallRecordingStreams:

    • Provides information about recorded streams, such as start time, end time, format, mixed/single type, etc.; can also be used to delete a recorded stream
    • accessible by the path: /api/callrecordingstreams (collection) or /api/callrecordingstreams/id (single item)
    • Supported HTTP methods: OPTIONS, GET, DELETE
  • CallRecordingFiles:

    • Provides information about recorded streams, such as start time, end time, format, mixed/single type, etc.; additionally returns the file content too
    • accessible by the path: /api/callrecordingfiles (collection) or /api/callrecordingfiles/id (single item)
    • Supported HTTP methods: OPTIONS, GET

6.26. SMS (Short Message Service) on Sipwise NGCP

Starting with its mr5.0.1 release, Sipwise NGCP offers short messaging service to its local subscribers. The implementation is based on a widely used software module: Kannel, and it needs to interact with a mobile operator’s SMSC in order to send and receive SMs for the local subscribers. The data exchange with SMSC uses SMPP (Short Message Peer-to-Peer) protocol.

SMS directions:

  • incoming / received: the destination of the SM is a local subscriber on the NGCP
  • outgoing / sent: the SM is submitted by a local subscriber
info

The Sipwise NGCP behaves as a short message client towards the SMSC of a mobile operator. This means every outgoing SM will be forwarded to the SMSC, and every incoming SM will reach the NGCP through an SMSC.

The architecture of the SMS components of NGCP and their interactions to other elements is depicted below, on a sip:carrier system:

SMS Interactions on NGCP

Figure 55. SMS Interactions on NGCP


info

For the sip:provider CE and PRO NGCP installations: the Kannel components and the ngcp-panel all run on the same single node. The description of SMS module will continue referring to a sip:carrier installation in the handbook.

There are 2 components of the SMS module:

  • SMS Box: this component takes care of handling the messages locally, that means:

    • delivering them to subscribers (writing into database for later retrieval)
    • picking up the submitted SMs from the database and forwarding them to the Bearer Box component
  • Bearer Box: this component manages the transmission of SMs between Sipwise NGCP and the mobile operator’s SMSC

6.26.1. Configuration

6.26.1.1. Main Parameters

The SMS function of NGCP is disabled by default. In order to enable SMS you have to change the value of configuration parameter sms.enable to yes in the main configuration file (/etc/ngcp-config/config.yml).

The second step of configuration is related to the SMSC where NGCP will connect to. You have to set the following parameters:

  • sms.smsc.host: IP address of the SMSC
  • sms.smsc.port: Port number of the SMSC
  • sms.smsc.username: Username for authentication on the SMSC
  • sms.smsc.password: Password for authentication on the SMSC

Other parameters of the SMSC connection may also need to be changed from the default values, but this is specific to each deployment.

Then, as usual, you have to make the new configuration active:

$ ngcpcfg apply 'Enabled SMS'
$ ngcpcfg push
6.26.1.2. Configuration Files of Kannel

There are a few configuration files for the Kannel module, namely:

  • /etc/default/ngcp-kannel: determines which components of Kannel will be started. This is auto-generated from /etc/ngcp-config/templates/etc/default/ngcp-kannel.tt2 file when SMS is enabled.
  • /etc/kannel/kannel.conf: contains detailed configuration of Kannel components. This is auto-generated from /etc/ngcp-config/templates/etc/kannel/kannel.conf.tt2 file when SMS is enabled.
  • /etc/logrotate.d/ngcp-kannel.conf: configuration of logrotate for Kannel log files. This is auto-generated from /etc/ngcp-config/templates/etc/logrotate.d/ngcp-kannel.conf.tt2 file when SMS is enabled.
caution

Please do not change settings in the above mentioned template files, unless you have to tailor Kannel settings to your specific needs!

Finally: see the description of each configuration parameter in the appendix Section 1.32, “sms”.

6.26.1.3. Call Forwarding for SMS (CFS)

Any subscriber registered on NGCP can apply a call forwarding setting for short messages, referred to as "CFS" (Call Forward - SMS). If the CFS feature is enabled, he can receive the SMs on his mobile phone, for example, instead of retrieving the SMs through the REST API. This is much more convenient for users if they do not have an application on their smartphone or computer that could manage the SMs through the REST API.

In order to enable CFS you have to set the forwarding as usual on the admin web interface, or through the REST API. Navigate to Subscribers → select one → Details → Preferences → Call Forwards and press the Edit button.

Call Forward for SMS

Figure 56. Call Forward for SMS


6.26.2. Monitoring, troubleshooting

6.26.2.1. Bearer Box (LB node of NGCP)

On the LB node you can see a process named "bearerbox". This process has 2 listening ports assigned to it:

  • 13000: this is the generic Kannel administration port, that belongs to the "core" component of Kannel.
  • 13001: this is the communication port towards the SMS Box component running on PRX nodes of NGCP.

The monit tool also shows the bearerbox process in its status information:

$ monit summary
...
Process 'kannel-bearerbox'          Running
...

The following log files can provide information about the operation of Bearer Box:

  • status messages and high level, short entries about sent and received messages: /var/log/ngcp/kannel/kannel.log

    ...
    2017-09-26 08:57:32 [15922] [10] DEBUG: boxc_receiver: heartbeat with load value 0 received
    ...
    2017-09-26 11:12:06 [15922] [10] DEBUG: boxc_receiver: sms received
    2017-09-26 11:12:06 [15922] [10] DEBUG: send_msg: sending msg to box: <192.168.1.4>
    2017-09-26 11:12:06 [15922] [11] DEBUG: send_msg: sending msg to box: <192.168.1.4>
    2017-09-26 11:12:06 [15922] [11] DEBUG: boxc_sender: sent message to <192.168.1.4>
    2017-09-26 11:12:06 [15922] [10] DEBUG: boxc_receiver: got ack
    ...
  • detailed information and message content of sent and received messages, link enquiries: /var/log/kannel/smsc.log

    info

    Sent and received message examples shown here do not contain the full phone number and content for confidentiality reason.

    • Example received message:

      ...
      2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP[default_smsc]: Got PDU:
      2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP PDU 0x7f2274025070 dump:
      2017-09-26 12:09:36 [15922] [6] DEBUG:   type_name: deliver_sm
      2017-09-26 12:09:36 [15922] [6] DEBUG:   command_id: 5 = 0x00000005
      2017-09-26 12:09:36 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
      2017-09-26 12:09:36 [15922] [6] DEBUG:   sequence_number: 11867393 = 0x00b51501
      2017-09-26 12:09:36 [15922] [6] DEBUG:   service_type: NULL
      2017-09-26 12:09:36 [15922] [6] DEBUG:   source_addr_ton: 2 = 0x00000002
      2017-09-26 12:09:36 [15922] [6] DEBUG:   source_addr_npi: 1 = 0x00000001
      2017-09-26 12:09:36 [15922] [6] DEBUG:   source_addr: "0660......."
      2017-09-26 12:09:36 [15922] [6] DEBUG:   dest_addr_ton: 1 = 0x00000001
      2017-09-26 12:09:36 [15922] [6] DEBUG:   dest_addr_npi: 1 = 0x00000001
      2017-09-26 12:09:36 [15922] [6] DEBUG:   destination_addr: "43668......."
      2017-09-26 12:09:36 [15922] [6] DEBUG:   esm_class: 0 = 0x00000000
      2017-09-26 12:09:36 [15922] [6] DEBUG:   protocol_id: 0 = 0x00000000
      2017-09-26 12:09:36 [15922] [6] DEBUG:   priority_flag: 0 = 0x00000000
      2017-09-26 12:09:36 [15922] [6] DEBUG:   schedule_delivery_time: NULL
      2017-09-26 12:09:36 [15922] [6] DEBUG:   validity_period: NULL
      2017-09-26 12:09:36 [15922] [6] DEBUG:   registered_delivery: 0 = 0x00000000
      2017-09-26 12:09:36 [15922] [6] DEBUG:   replace_if_present_flag: 0 = 0x00000000
      2017-09-26 12:09:36 [15922] [6] DEBUG:   data_coding: 3 = 0x00000003
      2017-09-26 12:09:36 [15922] [6] DEBUG:   sm_default_msg_id: 0 = 0x00000000
      2017-09-26 12:09:36 [15922] [6] DEBUG:   sm_length: 158 = 0x0000009e
      2017-09-26 12:09:36 [15922] [6] DEBUG:   short_message:
      2017-09-26 12:09:36 [15922] [6] DEBUG:    Octet string at 0x7f2274000f80:
      2017-09-26 12:09:36 [15922] [6] DEBUG:      len:  158
      2017-09-26 12:09:36 [15922] [6] DEBUG:      size: 159
      2017-09-26 12:09:36 [15922] [6] DEBUG:      immutable: 0
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 5a <14 bytes> 46
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 72 <14 bytes> 68
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 61 <14 bytes> 67
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 20 <14 bytes> 57
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 65 <14 bytes> 63
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 68 <14 bytes> 73
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 2e <14 bytes> 61
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 6c <14 bytes> 73
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 3a <14 bytes> 73
      2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 4d <14 bytes> 6e
      2017-09-26 12:09:36 [15922] [6] DEBUG:    Octet string dump ends.
      2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP PDU dump ends.
      2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP[default_smsc]: Sending PDU:
      2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP PDU 0x7f2274020790 dump:
      2017-09-26 12:09:36 [15922] [6] DEBUG:   type_name: deliver_sm_resp
      2017-09-26 12:09:36 [15922] [6] DEBUG:   command_id: 2147483653 = 0x80000005
      2017-09-26 12:09:36 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
      2017-09-26 12:09:36 [15922] [6] DEBUG:   sequence_number: 11867393 = 0x00b51501
      2017-09-26 12:09:36 [15922] [6] DEBUG:   message_id: NULL
      2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP PDU dump ends.
      2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (0.00,5.00)
      ...
    • Example sent message:

      ...
      2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (0.00,5.00)
      2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: Manually forced source addr ton = 1, source add npi = 1
      2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: Manually forced dest addr ton = 1, dest add npi = 1
      2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: Sending PDU:
      2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP PDU 0x7f2274025070 dump:
      2017-09-26 12:04:08 [15922] [6] DEBUG:   type_name: submit_sm
      2017-09-26 12:04:08 [15922] [6] DEBUG:   command_id: 4 = 0x00000004
      2017-09-26 12:04:08 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
      2017-09-26 12:04:08 [15922] [6] DEBUG:   sequence_number: 98163 = 0x00017f73
      2017-09-26 12:04:08 [15922] [6] DEBUG:   service_type: NULL
      2017-09-26 12:04:08 [15922] [6] DEBUG:   source_addr_ton: 5 = 0x00000005
      2017-09-26 12:04:08 [15922] [6] DEBUG:   source_addr_npi: 0 = 0x00000000
      2017-09-26 12:04:08 [15922] [6] DEBUG:   source_addr: "any"
      2017-09-26 12:04:08 [15922] [6] DEBUG:   dest_addr_ton: 1 = 0x00000001
      2017-09-26 12:04:08 [15922] [6] DEBUG:   dest_addr_npi: 1 = 0x00000001
      2017-09-26 12:04:08 [15922] [6] DEBUG:   destination_addr: "43676......."
      2017-09-26 12:04:08 [15922] [6] DEBUG:   esm_class: 3 = 0x00000003
      2017-09-26 12:04:08 [15922] [6] DEBUG:   protocol_id: 0 = 0x00000000
      2017-09-26 12:04:08 [15922] [6] DEBUG:   priority_flag: 0 = 0x00000000
      2017-09-26 12:04:08 [15922] [6] DEBUG:   schedule_delivery_time: NULL
      2017-09-26 12:04:08 [15922] [6] DEBUG:   validity_period: NULL
      2017-09-26 12:04:08 [15922] [6] DEBUG:   registered_delivery: 0 = 0x00000000
      2017-09-26 12:04:08 [15922] [6] DEBUG:   replace_if_present_flag: 0 = 0x00000000
      2017-09-26 12:04:08 [15922] [6] DEBUG:   data_coding: 0 = 0x00000000
      2017-09-26 12:04:08 [15922] [6] DEBUG:   sm_default_msg_id: 0 = 0x00000000
      2017-09-26 12:04:08 [15922] [6] DEBUG:   sm_length: 23 = 0x00000017
      2017-09-26 12:04:08 [15922] [6] DEBUG:   short_message:
      2017-09-26 12:04:08 [15922] [6] DEBUG:    Octet string at 0x7f227400c460:
      2017-09-26 12:04:08 [15922] [6] DEBUG:      len:  23
      2017-09-26 12:04:08 [15922] [6] DEBUG:      size: 24
      2017-09-26 12:04:08 [15922] [6] DEBUG:      immutable: 0
      2017-09-26 12:04:08 [15922] [6] DEBUG:      data: 44 <14 bytes> 73
      2017-09-26 12:04:08 [15922] [6] DEBUG:      data: 74 <5 bytes> 39
      2017-09-26 12:04:08 [15922] [6] DEBUG:    Octet string dump ends.
      2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP PDU dump ends.
      2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (1.00,5.00)
      ...
    • Example link enquiry:

      ...
      2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (0.00,5.00)
      2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP[default_smsc]: Got PDU:
      2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP PDU 0x7f2274020790 dump:
      2017-09-26 12:13:38 [15922] [6] DEBUG:   type_name: enquire_link
      2017-09-26 12:13:38 [15922] [6] DEBUG:   command_id: 21 = 0x00000015
      2017-09-26 12:13:38 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
      2017-09-26 12:13:38 [15922] [6] DEBUG:   sequence_number: 90764 = 0x0001628c
      2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP PDU dump ends.
      2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP[default_smsc]: Sending PDU:
      2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP PDU 0x7f2274025070 dump:
      2017-09-26 12:13:38 [15922] [6] DEBUG:   type_name: enquire_link_resp
      2017-09-26 12:13:38 [15922] [6] DEBUG:   command_id: 2147483669 = 0x80000015
      2017-09-26 12:13:38 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
      2017-09-26 12:13:38 [15922] [6] DEBUG:   sequence_number: 90764 = 0x0001628c
      2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP PDU dump ends.
      2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (0.00,5.00)
      ...
6.26.2.2. SMS Box (PRX node of NGCP)

On the PRX node you can see a process named "smsbox". This process has a listening port assigned to it: 13002, that is the communication port towards the Bearer Box component running on LB nodes.

The monit tool also shows the smsbox process in its status information:

$ monit summary
...
Process 'kannel-smsbox'             Running
...

The following log files can provide information about the operation of SMS Box:

  • sent and received messages using the API of WEB node: /var/log/kannel/smsbox.log

    info

    Sent and received message examples shown here do not contain the full phone number and content for confidentiality reason.

    • Example sent message:

      ...
      2017-09-26 12:16:42 [22763] [2] DEBUG: HTTP: Creating HTTPClient for `192.168.1.2'.
      2017-09-26 12:16:42 [22763] [2] DEBUG: HTTP: Created HTTPClient area 0x7f5dcc000ad0.
      2017-09-26 12:16:42 [22763] [3] INFO: smsbox: Got HTTP request </cgi-bin/sendsms> from <192.168.1.3>
      2017-09-26 12:16:42 [22763] [3] INFO: sendsms used by <sipwise>
      2017-09-26 12:16:42 [22763] [3] INFO: sendsms sender:<sipwise:43668.......> (192.168.1.3) to:<43676.......> msg:<...>
      2017-09-26 12:16:42 [22763] [3] DEBUG: Stored UUID ab95eb45-1ec0-4932-9863-1a95609a025f
      2017-09-26 12:16:42 [22763] [3] DEBUG: message length 52, sending 1 messages
      2017-09-26 12:16:42 [22763] [3] DEBUG: Status: 202 Answer: <Sent.>
      2017-09-26 12:16:42 [22763] [3] DEBUG: Delayed reply - wait for bearerbox
      2017-09-26 12:16:42 [22763] [0] DEBUG: Got ACK (0) of ab95eb45-1ec0-4932-9863-1a95609a025f
      2017-09-26 12:16:42 [22763] [0] DEBUG: HTTP: Destroying HTTPClient area 0x7f5dcc000ad0.
      2017-09-26 12:16:42 [22763] [0] DEBUG: HTTP: Destroying HTTPClient for `192.168.1.3'.
      ...
    • Example received message:

      ...
      2017-09-26 11:59:45 [22763] [5] INFO: Starting to service <...message content...> from <+43676-------> to <+43668------->
      2017-09-26 11:59:45 [22763] [10] DEBUG: Queue contains 0 pending requests.
      2017-09-26 11:59:45 [22763] [10] DEBUG: HTTPS URL; Using SSL for the connection
      2017-09-26 11:59:45 [22763] [10] DEBUG: Parsing URL `https://192.168.1.2:1443/internalsms/receive?auth_token=fNLosMgwdNUrKvEfFMm9
      &timestamp=2017-09-26+09:59:45&from=%2B43676-------&to=%2B43668-------&charset=UTF-8&coding=0&text=...':
      2017-09-26 11:59:45 [22763] [10] DEBUG:   Scheme: https://
      2017-09-26 11:59:45 [22763] [10] DEBUG:   Host: 192.168.1.2
      2017-09-26 11:59:45 [22763] [10] DEBUG:   Port: 1443
      2017-09-26 11:59:45 [22763] [10] DEBUG:   Username: (null)
      2017-09-26 11:59:45 [22763] [10] DEBUG:   Password: (null)
      2017-09-26 11:59:45 [22763] [10] DEBUG:   Path: /internalsms/receive
      2017-09-26 11:59:45 [22763] [10] DEBUG:   Query: auth_token=fNLosMgwdNUrKvEfFMm9&timestamp=2017-09-26+09:59:45&from=%2B43676-------
      &to=%2B43668-------&charset=UTF-8&coding=0&text=...
      2017-09-26 11:59:45 [22763] [10] DEBUG:   Fragment: (null)
      2017-09-26 11:59:45 [22763] [10] DEBUG: Connecting nonblocking to <192.168.1.2>
      2017-09-26 11:59:45 [22763] [10] DEBUG: HTTP: Opening connection to `192.168.1.2:1443' (fd=31).
      2017-09-26 11:59:45 [22763] [10] DEBUG: Socket connecting
      2017-09-26 11:59:45 [22763] [9] DEBUG: Get info about connecting socket
      2017-09-26 11:59:45 [22763] [9] DEBUG: HTTP: Sending request:
      2017-09-26 11:59:45 [22763] [9] DEBUG: Octet string at 0x7f5dbc00f470:
      2017-09-26 11:59:45 [22763] [9] DEBUG:   len:  382
      2017-09-26 11:59:45 [22763] [9] DEBUG:   size: 1024
      2017-09-26 11:59:45 [22763] [9] DEBUG:   immutable: 0
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 47 45 54 20 2f 69 6e 74 65 72 6e 61 6c 73 6d 73   GET /internalsms
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 2f 72 65 63 65 69 76 65 3f 61 75 74 68 5f 74 6f   /receive?auth_to
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 6b 65 6e 3d ...                                   ken=
                                                                ... 20 48 54 54 50 2f 31 2e 31 0d 0a         HTTP/1.1..
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 6b 65 65 70   Connection: keep
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 2d 61 6c 69 76 65 0d 0a 55 73 65 72 2d 41 67 65   -alive..User-Age
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 6e 74 3a 20 4b 61 6e 6e 65 6c 2f 31 2e 34 2e 34   nt: Kannel/1.4.4
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 0d 0a 48 6f 73 74 3a 20 31 39 32 2e 31 36 38 2e   ..Host: 192.168.
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 31 2e 32 3a 31 34 34 33 0d 0a 0d 0a               1.2:1443....
      2017-09-26 11:59:45 [22763] [9] DEBUG: Octet string dump ends.
      2017-09-26 11:59:45 [22763] [9] DEBUG: HTTP: Status line: <HTTP/1.1 200 OK>
      2017-09-26 11:59:45 [22763] [9] DEBUG: HTTP: Received response:
      2017-09-26 11:59:45 [22763] [9] DEBUG: Octet string at 0x7f5dbc006970:
      2017-09-26 11:59:45 [22763] [9] DEBUG:   len:  333
      2017-09-26 11:59:45 [22763] [9] DEBUG:   size: 1024
      2017-09-26 11:59:45 [22763] [9] DEBUG:   immutable: 0
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 53 65 72 76 65 72 3a 20 6e 67 69 6e 78 0d 0a 44   Server: nginx..D
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 61 74 65 3a 20 54 75 65 2c 20 32 36 20 53 65 70   ate: Tue, 26 Sep
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 20 32 30 31 37 20 30 39 3a 35 39 3a 34 35 20 47    2017 09:59:45 G
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 4d 54 0d 0a 43 6f 6e 74 65 6e 74 2d 54 79 70 65   MT..Content-Type
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 3a 20 74 65 78 74 2f 68 74 6d 6c 3b 20 63 68 61   : text/html; cha
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 72 73 65 74 3d 75 74 66 2d 38 0d 0a 43 6f 6e 74   rset=utf-8..Cont
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 65 6e 74 2d 4c 65 6e 67 74 68 3a 20 30 0d 0a 43   ent-Length: 0..C
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 6f 6e 6e 65 63 74 69 6f 6e 3a 20 6b 65 65 70 2d   onnection: keep-
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 61 6c 69 76 65 0d 0a 53 65 74 2d 43 6f 6f 6b 69   alive..Set-Cooki
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 65 3a 20 6e 67 63 70 5f 70 61 6e 65 6c 5f 73 65   e: ngcp_panel_se
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 73 73 69 6f 6e 3d 34 35 30 32 64 64 66 65 31 62   ssion=4502ddfe1b
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 63 31 65 33 39 30 65 30 64 36 66 39 64 34 37 30   c1e390e0d6f9d470
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 35 30 37 62 64 64 33 61 65 32 36 62 64 63 3b 20   507bdd3ae26bdc;
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 70 61 74 68 3d 2f 3b 20 65 78 70 69 72 65 73 3d   path=/; expires=
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 54 75 65 2c 20 32 36 2d 53 65 70 2d 32 30 31 37   Tue, 26-Sep-2017
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 20 31 30 3a 35 39 3a 34 35 20 47 4d 54 3b 20 48    10:59:45 GMT; H
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 74 74 70 4f 6e 6c 79 0d 0a 58 2d 43 61 74 61 6c   ttpOnly..X-Catal
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 79 73 74 3a 20 35 2e 39 30 30 37 35 0d 0a 53 74   yst: 5.90075..St
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 72 69 63 74 2d 54 72 61 6e 73 70 6f 72 74 2d 53   rict-Transport-S
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 65 63 75 72 69 74 79 3a 20 6d 61 78 2d 61 67 65   ecurity: max-age
      2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 3d 31 35 37 36 38 30 30 30 0d 0a 0d 0a            =15768000....
      2017-09-26 11:59:45 [22763] [9] DEBUG: Octet string dump ends.
      2017-09-26 11:59:45 [22763] [6] WARNING: Tried to set Coding field, denied.
      2017-09-26 11:59:45 [22763] [6] INFO: No reply sent, denied.
      2017-09-26 11:59:55 [22763] [9] DEBUG: HTTP: Server closed connection, destroying it <192.168.1.2:1443:1::><0x7f5db0000b20><fd:31>.
      ...
  • short log of sent/received messages: /var/log/kannel/smsbox-access.log

    ...
    2017-09-26 12:39:18 SMS HTTP-request sender:+43680------- request: '' url: 'https://192.168.1.2:1443/internalsms/receive?
    auth_token=fNLosMgwdNUrKvEfFMm9&timestamp=2017-09-26+10:39:18&from=%2B43680-------&to=%2B43668-------&charset=UTF-8&coding=0
    &text=<...message content...>' reply: 200 '<< successful >>'
    ...
    2017-09-26 12:41:54 send-SMS request added - sender:sipwise:43668------- 192.168.1.3 target:43680-------- request: '<...message content...>'
    ...

6.26.3. REST API

Handling of short messages from the user perspective happens with the help of NGCP’s REST API. There is a dedicated resource: https://<IP of WEB node>:1443/api/sms that allows you to:

  • Get a list of sent and received messages. This is achieved by sending a GET request on the /api/sms collection, as in the following example:

    curl -i -X GET -H 'Connection: close' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem \
      'https://example.org:1443/api/sms/?page=1&rows=10'
  • Retrieve an SM (both sent and received). This is achieved by sending a GET request for a specific /api/sms/id item, as in the following example:

    curl -i -X GET -H 'Connection: close' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem 'https://example.org:1443/api/sms/1'
  • Send a new message from a local subscriber. This is achieved by sending a POST request for the /api/sms collection, as in the following example:

    curl -i -X POST -H 'Connection: close' -H 'Content-Type: application/json' --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem \
      'https://example.org:1443/api/sms/'  --data-binary '{"callee" : "43555666777", "subscriber_id" : 4, "text" : "test"}'

As always, the full documentation of the REST API resources is available on the admin web interface of NGCP: https://<IP of WEB node>:1443/api/#sms