The Sipwise C5 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.
This section is going to give some hints to the reader about the Admin web interface of Sipwise C5. The notes here are generic and apply to most of the features that we discuss in the handbook in subsequent chapters.
When you look at or want to change various settings on Admin web interface you will see datatables or lists of particular items, e.g. Subscribers, Peering Groups, etc. Sometimes this kind of list can be really long and then it’s difficult to find the desired item there. To help the system administrator, the Sipwise C5 offers search filters for each of the lists / datatables. You have to simply type a search string (arbitrary text) in the Search textbox and the system will automatically filter the complete datatable for records that match the search string.
The Search String
The previous example shows what happens if you type a search string in the Search textbox. The search string will be applied to all visible columns of the datatable as a filter and all matching records are kept displayed.
The *
symbol can be used as wildcard for zero-or-more characters.
info | |
The |
While the search pattern is typically matched to values of all columns visible in the datatable, in some cases (i.e. unindexed columns) may be excluded from searching.
Each call appears in the subscriber’s Call History, except globally suppressed ones (if suppressing is configured), and you can apply search filters to the table as in case of other datatables.
The Call History datatable behaves slightly differently when it comes to wildcard
usage. The *
wildcard needs to be entered explicitly by the user if needed.
caution | |
Be aware that acceptable response times of the administrative web interface rely on utilizing available database indexes, which is impossible with a leading wildcard in the search string. Wildcards at the end of the search pattern do not impact performance. |
The Sipwise C5 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 C5.
Administrators, as user accounts, are also used for client authentication on the REST API of NGCP.
There is a single administrator (username: "administrator"), whose account is enabled by default and who belongs to the default reseller. This user is the superuser of Sipwise C5 administrative web interface (the so-called "admin panel"), and he has the right to modify administrators of other Resellers as well.
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.
You have 2 options:
There are some generic attributes that have to be set for each administrator:
1
, Name: default
), but the administrator has to be assigned
to his real reseller, if such an entity (other than default
) exists.
The second set of attributes is a list of access rights that are discussed in subsequent section of the handbook.
The various access rights of administrators are shown in the figure and summarized in the table below.
Table 2. 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 C5 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.
| |||
Show Passwords | Show passwords | The user sees subscriber passwords (in plain text) on the web interface.
| |||
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:
| |||
Show Billing Info | Billing data | Some REST API resources that are related to billing are disabled: HTTP requests
on | |||
Lawful Intercept | Lawful intercept | If the privilege is selected then the REST API for interceptions (that is:
|
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 (Network Class of Service) 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 Sipwise C5 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.
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.
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.
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.
You can change a list mode from one to the other at any time.
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.
Click the Close icon once you’re done editing your list.
For incoming call, the User Preference block_in_clir and adm_block_in_clir controls whether or not to reject incoming calls with number suppression (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.
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 the user- and administrative- levels.
In a case of a conflict, when the Block Lists feature allows a number and NCOS Levels rejects the same number or vice versa, the call will be rejected.
NCOS levels can either be whitelists or blacklists.
To create an NCOS Level, go to Settings→NCOS Levels and press the Create NCOS Level button.
Select a reseller, enter a name, select the mode and add a description, then click the Save button.
To define the rules within the newly created NCOS Level, click on the Patterns button of the level.
There are 2 groups of patterns where you can define matching rules for the selected NCOS Level:
info | |
Sipwise C5 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. |
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.
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:
^431
.
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).
An example of NCOS LNP Carrier definition:
In the above example we created a rule that blocks calls to "LNP_Carr1" carrier, supposing we use blacklist mode of the NCOS Level.
In the LNP NCOS Number Patterns view you can create multiple patterns to restrict NCOS LNP Carrier matching, one after the other. Click on the Create LNP Pattern Entry Button on top and fill out the form.
Considering the example before and adding the pattern shown in the picture,
the rule now blocks only calls to "LNP_Carr1" carrier that starts with 390
.
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. |
The below table gives an overview of all the possible combinations of NCOS and NCOS LNP Carrier:
Table 3. NCOS combinations
TYPE | NCOS | NCOS_LNP | RESULT |
---|---|---|---|
Whitelist | empty table | empty table | Blocked |
Whitelist | empty table | no match | Blocked |
Whitelist | empty table | match | Allowed |
Whitelist | no match | empty table | Blocked |
Whitelist | no match | no match | Blocked |
Whitelist | no match | match | Blocked* |
Whitelist | match | empty table | Allowed |
Whitelist | match | no match | Blocked* |
Whitelist | match | match | Allowed |
Blacklist | empty table | empty table | Allowed |
Blacklist | empty table | no match | Allowed |
Blacklist | empty table | match | Blocked |
Blacklist | no match | empty table | Allowed |
Blacklist | no match | no match | Allowed |
Blacklist | no match | match | Blocked |
Blacklist | match | empty table | Blocked |
Blacklist | match | no match | Blocked |
Blacklist | match | match | Blocked |
The parameter kamailio.proxy.lnp.strictly_check_ncos
contained in /etc/ngcp-config/config.yml
specify whether
the NCOS LNP should be evaluated even if the LNP lookup was not previously executed (because not required
by the inbound/outbound call) or if it didn’t return any occurence. If set to yes, a whitelist NCOS will
fail if the LNP lookup doesn’t return any match. The parameter has no impact on blacklist NCOS.
Once you’ve defined your NCOS Levels, you can assign them to local subscribers. To do so, navigate to Settings→Subscribers, 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.
You can assign the NCOS level to all subscribers within a particular domain. To do so, navigate to Settings→Domains, 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.
In some countries there are regulatory requirements that prohibit subscribers from forwarding their numbers to special numbers like emergency, police etc. While Sipwise C5 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.
The Sipwise C5 provides subscriber and domain preference allowed_ips to restrict the IP addresses that a particular subscriber or any subscribers within the respective domain 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, Sipwise C5 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 Settings→Subscribers→Preferences or Settings→Domains→Preferences, and search for the allowed_ips preference in the Access Restrictions section.
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.
The Sipwise C5 provides subscriber preference upn_block_list to restrict the CLI that subscriber is allowed to use the service from. If the INVITE request comes with a CLI that is not in the allowed list, Sipwise C5 will reject it with a 403 message. Also a voice message can be played when the call attempt is rejected (if configured).
The restriction is applied to User-Provided Number (UPN) which is obtained from the configurable source based on the setting of inbound_upn preference in the Access Restrictions section in the Domain and/or User preferences, after it has been rewritten with Inbound Rewrite Rules for Caller.
In case the inbound_upn preference is set to the "From Display-Name" the UPN value can be alpha-numeric so the access control supports the alpha-numeric (caller name) matching as well. If the incoming message does not have the Display-Name, though, the UPN value will be taken from the From-Username.
By default, upn_block_list is an empty list which means that subscriber is not restricted. If you want to configure a restriction, navigate to Settings→Subscribers, search for the subscriber you want to edit, press Details and then Preferences and press Edit for the upn_block_list preference in the Call Blockings section to define the list entries.
In block list entries, you can provide shell patterns like *
and []
. The CLI-based block list can either be whitelist or blacklist.
If separate preference upn_block_clir is enabled, incoming anonymous calls from this user will be dropped.
If the caller’s UPN is allowed it is also checked according to allowed_clis preference as usual and can be rewritten according to allowed_clis_reject_policy for correct calling number presentation on outgoing calls. This step happens after Access Control.
The Sipwise C5 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.
Currently 6 different types of Call Forward are available in Sipwise C5:
important | |
Starting from mr7.2.1 release, Call Forward Rerouting (CFR) has to be configured on the callee subscriber (in previous versions the preference associated to the caller subscriber). When the destination endpoint replies back with an error code, this will be matched with the one listed in the rerouting_codes and rerouting_mode callee’s preferences. |
Go to your Subscriber Preferences and click Edit on the Call Forward Type you want to set (e.g. Call Forward Unconditional).
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.
Beside call forwarding to a single destination, Sipwise C5 offers the possibility to activate call forwarding in a more sophisticated way:
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 - B-Number Set groups that determine all conditions under which the call will be forwarded.
Explanation of call forward parameters
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.
When you close the Destination Set Overview, you can now assign your new set in addition or instead of the quickset_cfu set.
Press Save to store your settings.
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.
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:
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.
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:
You will need to fill in the Name
field first, the Mode
: whitelist or blacklist,
the is_regex
flag and finally in the Source
field you can enter:
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)
is_regex
if set). Capturing groups
can be formed using parentheses and referenced in the Destination Set via \\1, \\2,…
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:
Once the Advanced View of the call forward definition has been opened, you will need to press the Manage B-Number Sets button to start defining new B-Number Sets or managing an existing one. The following image shows the B-Number Set definition dialog:
You will need to fill in the Name
field first, the Mode
: whitelist or blacklist,
the is_regex
flag and finally in the B-Number
field you can enter:
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)
is_regex
if set). Capturing groups
can be formed using parentheses and referenced in the Destination Set via \\1, \\2,…
You can add more patterns to the B-Number Set by pressing the Add another B-Number button. When you finished adding all patterns, press the Save button. You will then see the below depicted list of B-Number Sets:
As additional step you can define a Destination Set as described in Destination Sets subchapter. For our example, we have defined the following Destination Set:
A final step of defining the call forward settings is selecting a Destination,
a Time Set, a Source Set and a B-Number 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>
.
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 Set, Source Sets and B-Number Set provided, at SubscriberPreferences → Call Forwards location on the web interface:
The Sipwise C5 platform allows you to register multiple devices under the same subscriber. By the default, the maximum number of the device you can register is 5. This value is configurable via kamailio→proxy→max_registrations_per_subscriber preference in config.yml.
If a customer registers multiple devices, Sipwise C5 – once receives a call for that user – just send the call to all the registered devices, in parallel. All the devices will ring at the same time. This is called Parallel Forking, and this is the default behavior. The Sipwise C5 can also do the so-called Serial Forking, which means let ring one device first, then after a timeout let ring the next device, and so on and so forth. The Serial Forking feature can be activated setting subscriber/domain preference serial_forking_by_q_value.
Serial Forking is based on SIP Contact’s parameter called Q value, which is basically a priority number, set by the clients during their Registration. The q value is a floating point number in a range 0 to 1.0 specified as a parameter in the Contact header field. The higher the q value number, the more priority that device has. Contacts with q value 1.0 have maximum priority, so such contacts will be always tried first in serial forking. Contacts with q value 0 have the lowest priority and they will be tried after all other contacts with higher priority. In case two or more contacts have the same q value, then they are tried in parallel. This allow to create Parallel forking calls even if serial_forking_by_q_value preference is set.
In case the client doesn’t set the q value Sipwise C5 just set a default value of q=-1 in the database, which means that it’s not going to use it and it’s not going to perform any serial forking.
Q value can be also specified during the creation of a subscriber’s permanent registration (Details→Registered Devices→Create Permanent Registration).
If a subscriber with Serial Forking enabled receives a call, Sipwise C5 calls the registered devices one after the another. The forking is stopped only in the following cases:
The Sipwise C5 platform comes with two ways of accomplishing local number porting (LNP):
info | |
Accessing external LNP databases is available for PRO and CARRIER products only. |
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 Settings→Number Porting or via the API. The LNP configuration can be populated individually or via CSV import/export both on the panel and the API.
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 Sipwise C5 . 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.
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 makes it possible 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.
In order to activate Local LNP during routing, the feature must be activated in config.yml. Set kamailio→proxy→lnp→enable to yes and kamailio→proxy→lnp→type to local.
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 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 preference of the destination peer or subscriber/domain.
The Sipwise C5 provides means to allow or block calls towards ported numbers that are hosted by particular LNP carriers. Please visit Section 7.3.2.2, “Creating Rules per NCOS Level” in the handbook to learn how this can be achieved.
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.
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:
Table 4. 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) |
If a match in the local LNP table is found corresponding LNP Carrier code will be stored in CDR data.
Additionally two dedicated headers can be added to the outgoing SIP message:
P-NGCP-LNP-Number
: The returned LNP number, if any
P-NGCP-LNP-Status
: The LNP query return code (200 if successful, 404 if no entry found)
This feature is not enabled by default, but can be activated with the following parameters:
kamailio→proxy→lnp→add_reply_headers→enable
: no
kamailio→proxy→lnp→add_reply_headers→number
: P-NGCP-LNP-Number
kamailio→proxy→lnp→add_reply_headers→status
: P-NGCP-LNP-Status
As opposed to the Simple Emergency Number Handling solution, Sipwise C5 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, Sipwise C5 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 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 Sipwise C5 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, Sipwise C5 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:
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.
The administrative web panel of Sipwise C5 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:
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:
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:
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:
Rewrite Rules for Emergency Mapping
Once emergency containers and emergency mapping entries are defined, Sipwise C5 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 of the handbook. |
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
.
The Sipwise C5 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:
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
The CSV file for the upload has the same format as the one used for download.
The Sipwise C5 can potentially host privileged subscribers that offer emergency or at least prioritized services (civil defence, police etc.). In case of an emergency, the platform has to be free’d from any SIP flows (calls, registrations, presence events etc.) which do not involve those privileged subscribers.
Such an exceptional condition is called emergency mode and it can be activated for all domains on the system, or only for selected domains.
Once emergency mode is activated, Sipwise C5 will immediately apply the following restrictions on new SIP requests or existing calls:
Calls from non-privileged subscribers to emergency numbers are still allowed.
Typical call-flows of emergency mode will be shown in this section of the handbook. We have the following assumptions:
The examples do not show details of SIP messages, but rather give a high-level overview of the call-flows.
A non-privileged subscriber makes a call to another non-privileged subscriber. Result: the call will be rejected.
A non-privileged subscriber makes a call to an external subscriber (via peer). Result: the call will be rejected.
A non-privileged subscriber makes a call to a privileged subscriber. Result: the call will be accepted.
A non-privileged subscriber makes a call to an emergency number. Result: the call will be accepted.
A privileged subscriber makes a call to a non-privileged subscriber. Result: the call will be accepted.
A privileged subscriber makes a call to an external subscriber (via peer). Result: the call will be accepted.
The platform operator has to perform 2 steps of configuration so that the emergency mode can be activated. After the configuration is completed it is necessary to explicitly activate emergency mode, which can be accomplished as described in Section 7.8.3, “Activating Emergency Mode” later.
1. System-level Configuration
The emergency priorization function must be enabled for the whole system, otherwise
emergency mode can not be activated. The platform operator has to set kamailio.proxy.emergency_priorization.enabled
configuration parameter value to "yes"
in the main configuration file /etc/ngcp-config/config.yml
.
Afterwards changes have to be applied in the usual way, with the command: ngcpcfg
apply "Enabled emergency priorization"
In order to learn about other parameters related to emergency priorization please refer to Section 1.13, “kamailio” part of the handbook.
2. Subscriber-level Configuration
The platform operator (or any administrator user) has the capability to declare a subscriber privileged, so that the subscriber can initiate and receive calls when emergency mode has been activated on the NGCP. In order to do that the administrator has to navigate to Settings → Subscribers → select the subscriber → Details → Preferences → Internals → emergency_priorization on the administrative web interface, and press the Edit button.
The checkbox emergency_priorization has to be ticked and then press the Save button.
The same privilege can be added via the REST API for a subscriber: a HTTP PUT/PATCH
request must be sent on /api/subscriberpreferences/id
resource and the emergency_priorization
property must be set to "true"
.
The platform operator can activate emergency mode for a single or multiple domains in 3 different ways:
important | |
The interruption of ongoing calls is only possible with the command-line tool! Activating emergency mode for domains via the web interface or REST API will only affect upcoming calls. |
1. Activate emergency mode via web interface: this way of activation is more appropriate if only a single (or just a few) domain is affected. Please navigate to Settings → Domains → select a domain → Preferences → Internals → emergency_mode_enabled → Edit.
The checkbox emergency_mode_enabled has to be ticked and then press the Save button.
2. Activate emergency mode via REST API: this way of activation is more appropriate if only a single (or just a few) domain is affected.
For that purpose a HTTP PUT/PATCH request must be sent on /api/domainpreferences/id
resource and the emergency_mode_enabled
property must be set to "true"
.
3. Activate emergency mode using a command-line tool: Sipwise C5 provides a built-in script that may be used to enable/disable emergency mode for some particular or all domains.
Enable emergency mode:
> ngcp-emergency-mode enable <all|[domain1 domain2 ...]>
Disable emergency mode:
> ngcp-emergency-mode disable <all|[domain1 domain2 ...]>
Query the status of emergency mode:
> ngcp-emergency-mode status <all|[domain1 domain2 ...]>
Adding additional SIP headers to the initial INVITEs relayed to the callee
(second leg) is possible by creating a patchtt file for the following template:
/etc/ngcp-config/templates/etc/ngcp-sems/etc/ngcp.sbcprofile.conf.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 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. |
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, run
ngcpcfg apply 'Enable CODEC filtering'
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:
It could be useful to filter the received REGISTER and INVITE messages based on the User Agent header, for example if you want to force your subscribers to use certain types of devices.
To achieve that configuration system wide you just need to change the /etc/ngcp-config/config.yml
, in the following section:
kamailio: proxy: block_useragents: action: reject enable: yes mode: whitelist ua_patterns: - Yealink.*
In the example above, the system is allowing all the messages which have User Agent header starting with Yealink. All the others will be rejected with a 403 Forbidden message.
To silently drop the received message it is possible to specify the drop action instead of the default reject.
Another example is the blacklist
mode:
kamailio: proxy: block_useragents: action: drop enable: yes mode: blacklist ua_patterns: - friendly-scanner
In this example the system will block all the messages which have User Agent header equal to friendly-scanner. Because of the drop action this messages will be silently dropped, without providing any feedback to the sender. As usual, in order to apply the changes, run
ngcpcfg apply 'Enable User-Agent filtering'
Regardless of the system-wide configuration (UA filtering enabled or not), it is possible to define a specific User Agent filtering for each Domain or Subscriber. In order to do so, you should configure the following fields in Domain’s or Subscriber’s Preferences:
In case of rejection a message with code kamailio.proxy.early_rejects.block_admin.announce_code
and reason kamailio.proxy.early_rejects.block_admin.announce_reason
will be sent back to the subscriber.
For the purpose of external SIP-PBX interconnect with Sipwise C5 the platform admin should create a subscriber with multiple aliases representing the numbers and number ranges served by the SIP-PBX.
To configure the Subscriber, go to Settings→Subscribers 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.
Enable preference Number Manipulations→e164_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).
The following sections describe the recommended configuration for correct call routing and CLI presentation according to the SIPconnect 1.1 recommendation.
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 6.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 Sipwise C5 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 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
^(00|\+)([1-9][0-9]+)$
\2
International to E.164
Inbound
Caller
Inbound Rewrite Rule for Callee
^(00|\+)([1-9][0-9]+)$
\2
International to E.164
Inbound
Callee
Outbound Rewrite Rule for Caller
^([1-9][0-9]+)$
+\1
For the calls to SIP-PBX add plus to E.164
Outbound
Caller
Outbound Rewrite Rule for Callee
^([1-9][0-9]+)$
+\1
For the calls to SIP-PBX add plus to E.164
Outbound
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. |
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).
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:
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:
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, Details→Registered Devices→Create 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 Sipwise C5 will take care of routing the aliases to the AOR with e164_to_ruri preference. |
If a SIP-PBX cannot perform the digest authentication, you can authenticate it by its source IP address in Sipwise C5. To configure the IP-based authentication, go to the subscriber’s preferences (Details→ Preferences→Trusted 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, Sipwise C5 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, Sipwise C5 will not know which subscriber to charge for the call and will randomly select one. |
In some cases, when you have a device that cannot authenticate itself against Sipwise C5, 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 Sipwise C5.
In order to make a regular subscriber trusted, perform the following extra steps:
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.
The basic way of selecting the appropriate peering server, where an outbound call can be routed to, has already been described in Section 6.6.2.3, “Routing Order Selection” of the handbook.
This chapter provides information on the peer probing feature of Sipwise C5 that is available since the mr5.4.1 release.
The Sipwise C5 provides a 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 Sipwise C5 will fail over to another peering server (matching the corresponding peering
rules) after a timeout configured at system level (see the 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.
The system administrator has to configure the peer probing feature in 2 steps:
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.13, “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 Sipwise C5 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 Sipwise C5 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.
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
Enable probing of a peering server via the REST API
when you create a new peering server you will use an HTTP POST request and the target URL:
when you update an existing peering server you will use an HTTP PUT or PATCH request and the target URL:
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.
Peering server states, such as "reachable" / "unreachable", are continuously stored in a time-series database (InfluxDB type) by Sipwise C5 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, Sipwise C5 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 information for all nodes is stored in a table rooted at the
OID .1.3.6.1.4.1.34274.1.1.2.40.2.1
with the following OID path:
.iso.org.dod.internet.private.enterprises.sipwise.ngcp.ngcpObjects.ngcpMonitor.ngcpMonitorPeering.psTable
The peer status is an indexed element of that table at the OID
.1.3.6.1.4.1.34274.1.1.2.40.2.1.7
with the following OID path:
.iso.org.dod.internet.private.enterprises.sipwise.ngcp.ngcpObjects.ngcpMonitor.ngcpMonitorPeering.psTable.psEntry.psPeerStatus
Value of psPeerStatus can be:
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. |
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.
A new configuration template: /etc/ngcp/config/templates/etc/kamailio/proxy/probe.cfg.tt2
is introduced to handle outbound probing requests.
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.
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.
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.
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.
The following list shows you how the voicebox menu is structured.
1 Read voicemail messages
3 Advanced options
9 Save message in a folder
2 Change folders
3 Advanced Options
0 Mailbox options
1 Record your unavailable message
2 Record your busy message
3 Record your name
4 Record your temporary greetings
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.
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.
Recorded name
is unavailable."
Digits-of-number-dialed
is unavailable".
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.
Recorded name
is busy."
Digits-of-number-dialed
is busy."
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.
The Voicemail system allows you to save and organize your messages into folders. There can be up to ten folders.
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.
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.
This section shows flowcharts of calls to the voicemail system. Flowcharts contain the name of prompts as they are identified among Asterisk voice prompts.
The language for the Voicemail system IVR or Vertical Service Codes (VSC) IVRs may be set using the subscriber or domain preference language.
The Sipwise C5 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 Sipwise C5 Panel and uploaded by the administrator in his language of choice.
The Sipwise C5 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). Additionally Sound Sets can be configured on Peer level in order to play a dedicated early reject prompt when an incoming call doesn’t match any local subscriber. Sound Sets can be defined in Settings→Sound Sets. To create a new Sound Set, click Create Sound Set. Then click the Files button.
info | |
You may use 8 or 16 bit mono WAV audio files for all of the voice prompts. |
Sound_Set and Contract_Sound_Set are used for different purposes:
The Music on Hold prompts can be uploaded to both Contract_Sound_Set and Sound_Set. In this case, the one from the Sound_Set will take precedence. Vice versa, digits prompts in Contract_Sound_Set will take precedence.
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.
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 Sipwise C5 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 5. Early Reject Announcements
Handle | Description | Message played |
---|---|---|
| This is an announcement that the calling party hears before
the call is being actually sent to the destination. The feature can be activated with
Applications / | N/A (custom message, no default) |
| 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 / | N/A (custom message, no default) |
| This is an announcement that the calling party hears before
the call is actually sent to the destination and before the recording starts. The feature
can be activated with Applications / | N/A (custom message, no default) |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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 | The emergency number you have dialed is not available in your region. |
| 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. |
| 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 | An error has occurred. Please try again later. |
| 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. |
| 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. |
| Announcement played on outgoing call to subscriber that is locked for outgoing calls | You are currently not allowed to place outbound calls. |
| 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. |
| 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. |
| 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 | The network you are trying to reach is currently busy. Please try again later. |
| 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. |
| 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. |
| When the VSC (Vertical Service Code) service is disabled in domain or
subscriber preferences (Access Restrictions / | N/A (custom message, no default) |
| 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. |
| 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. |
| PLEASE NOTE: This announcement is already obsolete, as of Sipwise C5 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 Sipwise C5 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 6. Additional Early Reject Reason Codes
Handle | Description |
---|---|
| Caller blocked by |
| Callee blocked by subscriber preference |
| Caller blocked by subscriber preference |
| Caller blocked by customer preference |
| Callee is a PBX group with 0 members. Announcement
|
| Callee is a PBX group and we have a timeout (i.e. no
group member could be reached). Announcement |
| PLEASE NOTE: This handle refers to the same early reject
case as |
The Sipwise C5 makes it possible to play an announcement on behalf of callee server failure in case of outbound calls. The features can be activated on Subscribers and on Peers. For example: if subscriber A calls subscriber B and B refuses the call with code 404 without providing any announcement, Sipwise C5 can be configured to play a customized announcement to A on behalf of B.
To activate this feature, first create a system Sound Set, or use an already existing one, and then assign it to the callee subscriber. Upload in the Sound Set one or more announcements. Once the Sound Set is configured, the subscriber’s preference announce_error_codes_enable must be enabled under Subscriber → Preferences → NAT and Media Flow Control menu. Last step is to list in the subscriber’s preference announce_error_codes_list the announcements that will be played to the caller in case a particular error code is returned back from the callee. Each entry of the list has to be a string composed in the following way: <error_code>;<announcement_name>, where error_code is the SIP return code and announcement_name is name of the announcement taken from the sound_set list. Returning to the example above, to play callee_unknown message in case of 404 returned from the callee, the entry 404;callee_unknown has to be added in announce_error_codes_list preference.
The same feature is available for peer as well.
important | |
In case announce_error_codes_enable is enabled, it is important that the remote endpoint doesn’t play any announcement for error codes listed in announce_error_codes_list otherwise the final result will be to have two announcements: one generated by the remote endpoint and one generated by Sipwise C5. |
The Sipwise C5 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/:
Go to your Subscriber Preferences and click Edit on the Call Forward Type you want to set (e.g. Call Forward Unconditional).
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.
Sound Sets can be defined in Settings→Sound Sets. To create a new Sound Set, click Create Sound Set. Then click the Files button.
Upload the following files:
Table 7. Conference Sound Sets
Handle | Message 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).
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.
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.
The following 2 sections show flowcharts with voice prompts that are played to a caller when he dials the conference.
MCID feature allows customers to report unwanted calls to the platform operator.
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
Finally you run ngcpcfg apply "Enabling MCID"
to recreate the templates and automatically restart depended services.
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.
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.
The preferences a subscriber can provision by himself via the CSC can be limited via profiles within profile sets assigned to subscribers.
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 Settings→Subscriber Profiles. To create a new Profile Set, click 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.
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. |
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:
In order to detect a SIP loop ( incoming call as a response for a call request ) Sipwise C5 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
.
Content and vision of the invoices are customizable by invoice templates.
info | |
The Sipwise C5 generates invoices in pdf format. |
Invoices can be requested for generation, searched, downloaded and deleted on the administrative web interface. Navigate to Settings → Invoices menu and you get a list of all invoices currently stored in the database.
tip | |
The system operator or a third party application can also generate, list, retrieve and delete invoices via the REST API. Please read further details here. |
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:
All form fields are mandatory.
Generated invoice can be downloaded as pdf file.
To do it press button "Download" against invoice in the invoice management interface.
Respectively press on the button "Delete" to delete invoice.
Besides managing invoices on the admin web interface of NGCP, the system administrator (or a third party system) has the opportunity to request generation and retrieval of invoices via the REST API.
The subsequent sections describe the available operations for invoice management
with API requests in details. All operations work on the Invoices resource and
use the /api/invoices
base path. The authentication method is username/password
in the examples given below, however it is recommended to use a TLS client certificate
for authentication on the REST API.
info | |
The full API documentation is always available at the location:
|
The prerequisite for generating a new invoice is that the customer has to have an invoice template assigned to him.
The following example shows a CURL command that will request generation of an invoice:
curl -i -X POST -H 'Connection: close' -H 'Content-Type: application/json' \ --user adminuser:adminpwd -k 'https://127.0.0.1:1443/api/invoices/' \ --data-binary '{ "customer_id" : "79", "template_id" : "1", \ "period_start": "2017-11-01 00:00:00", "period_end": "2017-11-30 23:59:59" }'
Please note that in this operation we used the /api/invoices
path (the invoices
collection) and a POST request on it to create a new invoice item.
In case of a successful operation, Sipwise C5 will reply with 201 Created
HTTP status
and send the ID of the invoice in Location header. In our example the new invoice
item may be directly referred as /api/invoices/3
(ID = 3).
HTTP/1.1 201 Created Server: nginx Date: Tue, 14 Nov 2017 13:38:40 GMT Content-Length: 0 Connection: close Location: /api/invoices/3 Set-Cookie: ngcp_panel_session=d5e4a8dd003fd7cac646653a6b5aefa703cf3e66; path=/; expires=Tue, 14-Nov-2017 14:38:38 GMT; HttpOnly X-Catalyst: 5.90114 Strict-Transport-Security: max-age=15768000
In case of a failed operation, e.g. when we request an invoicing period that is
invalid for the customer, Sipwise C5 will reply with 422 Unprocessable Entity
or
500 Internal Server Error
HTTP status.
You can download properties / data of a specific invoice by selecting the item by its ID, using an HTTP GET request.
curl -i -X GET -H 'Connection: close' --user adminuser:adminpwd -k \ 'https://127.0.0.1:1443/api/invoices/3'
The above request will return a JSON data structure containing invoice properties:
HTTP/1.1 200 OK Server: nginx Date: Wed, 15 Nov 2017 12:13:04 GMT Content-Type: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/"; charset=utf-8 Content-Length: 759 Connection: close Link: </api/invoices/>; rel=collection Link: <http://purl.org/sipwise/ngcp-api/>; rel=profile Link: </api/invoices/3>; rel="item self" Link: </api/invoices/3>; rel="item http://purl.org/sipwise/ngcp-api/#rel-invoices" Link: </api/customers/79>; rel="item http://purl.org/sipwise/ngcp-api/#rel-customers" Set-Cookie: ngcp_panel_session=219feccbee4fa936defd1ee511c84efe7b5a6d6a; path=/; expires=Wed, 15-Nov-2017 13:13:03 GMT; HttpOnly Strict-Transport-Security: max-age=15768000 { "_links" : { "collection" : { "href" : "/api/invoices/" }, "curies" : { "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}", "name" : "ngcp", "templated" : true }, "ngcp:customers" : { "href" : "/api/customers/79" }, "ngcp:invoices" : { "href" : "/api/invoices/3" }, "profile" : { "href" : "http://purl.org/sipwise/ngcp-api/" }, "self" : { "href" : "/api/invoices/3" } }, "amount_net" : 0, "amount_total" : 0, "amount_vat" : 0, "id" : 3, "period_end" : "2017-11-30T23:59:59+00:00", "period_start" : "2017-11-01T00:00:00+00:00", "sent_date" : null, "serial" : "INV2017110000003" }
It is also possible to query the complete invoices collection and use a filter (e.g. invoicing period, customer ID, etc.) to get the desired invoice item. In the example below we request all available invoices that belong to the customer with ID "79".
curl -i -X GET -H 'Connection: close' --user adminuser:adminpwd -k \ 'https://127.0.0.1:1443/api/invoices/?customer_id=79'
The returned dataset is now slightly different because it is represented as an array of items, although in our example the array consist of only 1 item:
{ "_embedded" : { "ngcp:invoices" : [ { "_links" : { "collection" : { "href" : "/api/invoices/" }, "curies" : { "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}", "name" : "ngcp", "templated" : true }, "ngcp:customers" : { "href" : "/api/customers/79" }, "ngcp:invoices" : { "href" : "/api/invoices/3" }, "profile" : { "href" : "http://purl.org/sipwise/ngcp-api/" }, "self" : { "href" : "/api/invoices/3" } }, "amount_net" : 0, "amount_total" : 0, "amount_vat" : 0, "id" : 3, "period_end" : "2017-11-30T23:59:59+00:00", "period_start" : "2017-11-01T00:00:00+00:00", "sent_date" : null, "serial" : "INV2017110000003" } ] }, "_links" : { "curies" : { "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}", "name" : "ngcp", "templated" : true }, "ngcp:invoices" : { "href" : "/api/invoices/3" }, "profile" : { "href" : "http://purl.org/sipwise/ngcp-api/" }, "self" : { "href" : "/api/invoices/?page=1&rows=10" } }, "total_count" : 1 }
You can download a specific invoice as a PDF file in the following way:
curl -X GET -H 'Connection: close' -H 'Accept: application/pdf' \ --user adminuser:adminpwd -k 'https://127.0.0.1:1443/api/invoices/3' > result.pdf
Please note that in the example above we do not add the "-i" option that would also include the headers of the HTTP response in the output file. The output of the CURL command, i.e. the PDF file, is saved as "result.pdf" locally.
In order to delete an invoice item you have to send a DELETE request on the specific item:
curl -i -X DELETE -H 'Connection: close' --user adminuser:adminpwd -k \ 'https://127.0.0.1:1443/api/invoices/3'
In case of successful deletion Sipwise C5 should send HTTP status 204 No Content
as
a response:
HTTP/1.1 204 No Content Server: nginx Date: Wed, 15 Nov 2017 13:42:42 GMT Connection: close Set-Cookie: ngcp_panel_session=10b66a6baf25a09739c2bb2377c70ecceee78387; path=/; expires=Wed, 15-Nov-2017 14:42:42 GMT; HttpOnly X-Catalyst: 5.90114 Strict-Transport-Security: max-age=15768000
Invoice template defines structure and look of the generated invoices. The Sipwise C5 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.
Invoice templates can be searched, created, edited and deleted in the invoice templates management interface.
Invoice template creation is separated on two steps:
To register new invoice template press "Create Invoice Template" button.
On the invoice template meta information form following parameters can be specified:
All form fields are mandatory.
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.
Invoice template is a XML SVG source, which describes content, look and position of the text lines, images or other invoice template elements. The Sipwise C5 provides embedded WYSIWYG SVG editor svg-edit 2.6 to customize default template. The Sipwise C5 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:
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.
To return to Sipwise C5 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:
To see all invoice template layers, press on "Layers" vertical sign on right side of the svg-edit interface:
Side panel with layers list will be shown.
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.
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:
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:
And then save invoice template changes.
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
After image uploaded save invoice template changes.
To save invoice template content changes press button "Save SVG".
You will see message about successfully saved template. You can preview your invoice look in PDF format. Press on "Preview as PDF" button.
Invoice preview will be opened in the new window.
info | |
Example fake data will be used for preview generation. |
The Sipwise C5 makes it possible to customize content of the emails sent on the following actions:
Default email templates for each of the email events are inserted on the initial Sipwise C5 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 Sipwise C5 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 Sipwise C5 Panel code.
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 | |
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:
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 | |
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:
Template name | invoice_default_email |
From | |
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:
info | Invoice fields |
---|---|
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 |
info | Contact fields example for the "provider". Replace "provider" to client to access proper "customer" contact fields. |
---|---|
|
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.
To create new email template press button "Create Email Template".
On the email template form all fields are mandatory:
Name: currently only email template with the following names will be considered by Sipwise C5 on the appropriate event :
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 6.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*01000
, and disable it by dialing #72
.
*90*01000
, and disable it by dialing #90
.
*92*30*01000
, and disable it by dialing #92
.
*93*01000
, and disable it by dialing #93
.
*50*101000
, which then can be used by dialing *1
. There is no code to disable a speed dial slot. When a slot is no longer necessary, it can be ultimately removed using the web interface or can be just ignored, because it is not impacting the calls from and to this subscriber.
*55*0830
.
*31*01000
.
*32*
, and disable it by dialing #32
.
*80*789001000
to call 431000 bypassing block lists.
You can change any of the codes (but not the format) in /etc/ngcp-config/config.yml in the section sems→vsc. 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 Sipwise C5 via SIP like normal telephone calls. |
Table 8. 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. |
WebRTC is an open project prroviding 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.
Sipwise C5 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:
The transport_protocol
setting may change, depending on your WebRTC client/browser configuration. Supported protocols are the following:
warning | |
The belowr configuration is enough to handle a WebRTC client/browser. As mentioned, you may need to tune a little bit your |
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 Sipwise C5 to translate between Plain RTP and RTP/SAVPF when you have calls between normal SIP clients and WebRTC clients.
Instant Messaging (IM) based on XMPP comes with Sipwise C5 out of the box. Sipwise C5 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
.
Sipwise C5 provides an opportunity to record call media content and store that in files. This function is available since mr5.3.1 version of Sipwise C5 .
Some characteristics of the Call Recording:
Activation of call recording may happen generally for a Domain / Peer / Subscriber through Sipwise C5 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. |
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:
config.yml
configuration file.
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:
rtpproxy.recording.output_mixed = ‘yes’
(combined stream required)
rtpproxy.recording.output_single = ‘no’
(unidirectional streams not required)
rtpproxy.recording.output_mixed = ‘no’
(combined stream not required)
rtpproxy.recording.output_single = ‘yes’
(unidirectional streams required)
rtpproxy.recording.output_mixed = ‘yes’
(combined stream required)
rtpproxy.recording.output_single = ‘yes’
(unidirectional streams required)
The Call Recording function can be enabled and configured on Sipwise C5 by changing
the following configuration parameters in config.yml
file:
rtpproxy: ... recording: enable: 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
Enabling the function requires changing the value of rtpproxy.recording.enable
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:
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. |
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 Sipwise C5 system state with ngcp-service tool:
root@sp1:/etc/ngcp-config# ngcp-service summary Ok Service Managed Started Status -- ------------------------------ ---------- --------- --------- … kamailio-lb managed by-ha active ngcp-voisniff managed by-ha active rtpengine managed by-ha active rtpengine-recording managed by-ha active …
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.
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
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.
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)
format
is shown, that can be either "wav", or "mp3"
The Sipwise C5 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:
/api/callrecordings
(collection) or /api/callrecordings/id
(single item)
CallRecordingStreams:
/api/callrecordingstreams
(collection) or /api/callrecordingstreams/id
(single item)
CallRecordingFiles:
/api/callrecordingfiles
(collection) or /api/callrecordingfiles/id
(single item)
Many country regulations require that an informative announcement is played to the caller before the call is actually recorded. The Sipwise C5 allows you to configure your own custom announcement with few simple steps.
First 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 an announcement early_rejects → announce_before_recording for that purpose.
Once the Sound Set is created the subscriber’s preference play_announce_before_recording of the callee must be enabled under Subscriber → Preferences → Applications menu. The same parameter can be set in the Domain’s or Customer’s preferences to enable this feature for all its subscribers.
info | |
The announcement will be played to caller before the call is routed to the callee. |
important | |
In case of CFU or CFNA with Pre-Recording Announcement feature enabled on both the forwarder and the final callee, only the Announcement of final callee will be played to caller. In case of CFB and CFT, instead, the announcement of the forwarder will be played first, then the announcement of final callee will be played after the call forward is executed. |
Starting with version mr6.2.1, Sipwise C5 offers the capability to convert RTP media between several supported codecs, a feature known as transcoding. While this feature is always available on Sipwise C5, it’s engaged only when a subscriber, peer, or domain is explicitly configured for it. By default, Sipwise C5 lets RTP endpoints negotiate the codec to use among themselves without interfering.
important | |
Media transcoding is a relatively CPU-intensive feature. As such, each individual node of a Sipwise C5 performing media transcoding can only support a limited number of concurrent calls for which transcoding is active. |
The following audio codecs, which are commonly found in use by SIP/RTP clients, are currently supported for transcoding.
Some codecs operate at different sampling rates than other codecs. If transcoding happens between two such codecs, the audio will be resampled as necessary. Similarly, if transcoding happens between a mono (1-channel) and a stereo (2-channel) codec, the audio will be up-mixed and down-mixed as necessary.
Transcoding can be engaged for individual subscribers, peers, or domains on their respective preferences page in the Sipwise C5 admin web interface.
Setting any of the transcoding options for a domain makes it affect all the subscribers in this domain.
Individual options are described below.
Packetisation time in milliseconds. Normally Sipwise C5 lets the
RTP endpoints select and negotiate the packetisation time they want to use.
Setting this option to anything other than unchanged
will engage the
transcoding engine towards this subscriber or peer even if none of the
other transcoding options are set, in which case the media will simply be
repacketised.
For example, setting this to 40 ms
would mean that each RTP
packet sent towards this subscriber or peer would contain 40
milliseconds worth of audio, even if the other side of the call sends media that
is packetised differently. It would also make Sipwise C5 indicate towards
this subscriber or peer that it would prefer to receive audio in 40
millisecond packets (through the a=ptime
SDP attribute).
Enabling one of these options adds the selected codecs to the list of codecs offered to this subscriber or peer, even if the original list of offered codecs did not include it. If this additional codec ends up being accepted by this subscriber or peer, then it will be transcoding to the first supported codec that was originally offered.
For example, if a calling RTP client A indicates support for PCMA (G.711 a-Law) as well as G.722, and calls a subscriber B that is configured for transcoding to G.729, then subscriber B would be offered PCMA, G.722, and G.729 by Sipwise C5. If subscriber B then accepts G.729 and starts sending G.729, Sipwise C5 would engage its transcoding engine and transcode the audio to PCMA (because PCMA and not G.722 was the codec preferred by A) before forwarding it to A. Vice versa, PCMA arriving from A would be transcoded to G.729 before being sent to B. (If B were to reject G.729 and instead starts to send PCMA or G.722, no transcoding would happen.)
Notes on individual codecs:
AMR
operating at 8 kHz) and wideband
(AMR-WB
operating at 16 kHz) variants. These are distinct codecs and can be
configured for transcoding separately or together.
Some codecs (Opus and G.723.1 in particular) can be configured for different bitrates, which would impact the amount of network bandwidth they use, as well as the audio quality produced. For Opus, different bitrates can be selected for their mono and stereo instances. Selecting a bitrate has no effect if transcoding to the respective codec is not engaged.
Setting this flag instructs Sipwise C5 to always engage transcoding to the first (preferred) codec indicated by an RTP endpoint, even if another codec is available that is supported by both parties to a call. Enabling this flag can potentially engage the transcoding engine for a call even if none of the other transcoding options are set.
For example: Subscriber A is calling subscriber B. Subscriber A is indicating
support for PCMA and G.722. Subscriber B answers the call, rejects PCMA but
accepts G.722, and starts sending G.722 to A. Normally Sipwise C5 would not
get involved and would simply let G.722 pass between A and B. But if subscriber
B has the always_transcode
flag set, Sipwise C5 would now start
transcoding the G.722 sent by B into PCMA before forwarding it to A, because
PCMA was indicated as the preferred codec by A. Vice versa, PCMA arriving from A
would be transcoded into G.722 and then forwarded to B.
Sipwise C5 supports transcoding between DTMF event packets (using the RTP
telephone-event
type payload) and DTMF tones carried in-band in the audio
stream. DTMF transcoding is supported in both directions: transcoding DTMF event
packets to DTMF tones, and DTMF tones in an audio stream and transcoding them to
DTMF event packets.
Support for DTMF transcoding can be enabled in one of two ways:
transcode_dtmf
for a subscriber, peer, or domain. This
is useful if the subscriber, peer, or domain requires support for DTMF event
packets, but the calling entity might only support DTMF tones carried in-band in
the audio stream.
always_transcode
for a subscriber, peer, or domain.
This is useful for the reverse case: if the subscriber, peer, or domain might
only support DTMF tones carried in-band in the audio stream, but the calling
entity requires support for DTMF event packets.
Enabling DTMF transcoding for any call requires that all audio passes through the transcoding engine, as well as a DSP for detecting DTMF tones in one direction. This carries an additional performance impact with it, and so DTMF transcoding should only be enabled when really necessary.
This feature allows a callee to play a custom announcement to the caller every time it receives a call. The announcement is played in early media mode, therefore it can be used as a simple business welcome message or to inform the caller about a different cost of the call before it will be actually charged.
The configuration of the announcement is similar to the activation of Pre-Recording Announcement and it requires few simple steps.
First 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 an announcement early_rejects → announce_before_call_setup for that purpose.
Once the Sound Set is created the subscriber’s preference play_announce_before_call_setup must be enabled under Subscriber → Preferences → Applications menu. The same parameter can be set in the Domain’s or Customer’s preferences to enable this feature for all its subscribers.
info | |
The announcement will be played to caller before the call is routed to the callee. |
important | |
Differently from Pre-Recording Announcement, in all Call Forward cases with Announcement Before Call Setup feature enabled on both the forwarder and the final callee, only the announcement of the forwarder will be played to caller. |
This feature and Pre-Recording Announcement can be activated at the same time. In this case the Announcement Before Call Setup will be played as first.
Starting with its mr5.0.1 release, Sipwise C5 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:
info | |
The Sipwise C5 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 Sipwise C5 through an SMSC. |
The architecture of the SMS components of Sipwise C5 and their interaction with other elements is depicted below:
info | |
For the Sipwise C5 CE and PRO 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 Sipwise C5 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:
The SMS functionality of Sipwise C5 is disabled by default. In order to enable SMS,
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 Sipwise C5 will connect 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'
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.
Any subscriber registered on Sipwise C5 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.
On the LB node you can see a process named "bearerbox". This process has 2 listening ports assigned to it:
The ngcp-service tool also shows the bearerbox process in its summary information:
$ ngcp-service summary Ok Service Managed Started Status -- ------------------------------ ---------- --------- --------- … kannel-bearerbox managed by-ha active …
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) ...
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 ngcp-service tool also shows the smsbox process in its summary information:
$ ngcp-service summary Ok Service Managed Started Status -- ------------------------------ ---------- --------- --------- … kannel-smsbox managed by-ha active …
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 ×tamp=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×tamp=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×tamp=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...>' ...
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
The Sipwise C5 provides administrative WEB and API interface to manage time sets.
Supported fields, input and output format are based on iCalendar EVENT specification.
Not all iCalendar and EVENT properties are supported, but those that are used for time points and periods definition or stated mandatory by specification:
CALENDAR supported properties:
EVENT supported properties:
Important to mention that current implementation does not support these EVENT properties:
Main EVENT property, that is used for time points and periods definition is RRULE. Current time sets implementation supports all properties described in the RRULE specification except WKST.
Default value for week start is MO (Monday).
Time sets management section is provided in two variants. One is main time sets management section and other is a chapter on reseller details page. Variants have minor differences. Functionality will be explained using time sets dedicated interface. Differences will be explained below.
Time set can be created using creation form. On time sets management interface press button "Create Time Set Entry":
"Reseller" field is mandatory.
"Name" field should be defined, if iCalendar (ics) file is not going to be uploaded or file doesn’t have NAME property for the CALENDAR entry.
If both NAME in the uploaded iCalendar (ics) file and form field "Name" aren’t empty then value from the form field will be taken.
Created time set can be modified:
or deleted:
info | |
If calendar ics file will be uploaded to edit time set, all presented events will be deleted and events from the uploaded file will be added after it. |
Time set can contain set of events. Each time set event will be used to generate CALENDAR EVENT entry in the generated iCalendar file. So all fields in the time set event forms represent properties of the iCalendar EVENT component.
To manage time set events press "Events" button against proper time set.
Events management section will appear:
To create event press "Create Event" button.
Form to create event will be shown:
"Start" field reflects DTSTART property of the EVENT. "Start" is mandatory and by default is set to the start of the current day. "Start" value format is datetime.
"Stop" field reflects DTEND property of the EVENT. For the events within recurrence "Stop" will define duration of each iteration.
To specify "Stop" datetime, press button "Set".
Fields to enter DTEND date and time will appear:
To return "Stop" field to the empty value press button "None". Value in the form fields will be preserved, but newly created EVENT will have empty DTEND property.
Other fields in the form are optional. Most of them aren’t visible by default and will be shown if requested by user or required by data into other fields.
RRULE property of the EVENT is a recurrence rule and defines set of the iterations for the EVENT.
To customize recurrence rule for the EVENT select proper repetition unit for the "Repeat" form field. Input field for the recurrence interval will appear left to the frequency select.
According to the selected unit, FREQ property of the EVENT RRULE will be set to one of the: SECONDLY, MINUTELY, HOURLY, DAYLY, WEEKLY, MONTHLY, YEARLY.
To specify end of the EVENT iterations, select "Series stop" value. For the "at date" option will be shown input for the date and time that will define UNTIL property of the EVENT RRULE.
"after" option, respectively, will put entered value to the COUNT property of the EVENT RRULE.
Form fields "By hour", "By week day", "By month", "By month day", "By set position", "By week number", "By year day", "By second" and "By minute" aren’t shown by default. To enter value to any of these fields press according button on the left. Button with field name is grayed off when corresponding EVENT property is empty.
When gray button with field name is pressed, field input control appears on the right. In the same time button with field name becomes orange, indicating that field value will be saved for the EVENT.
Fields with checkboxes controls have auxiliary button "Invert selection". When button "Invert selection" is pressed currently empty checkboxes become selected and currently selected checkboxes become empty.
When form data will be saved, checkboxes values will be saved as coma separated numbers.
BYxxx RRULE properties expand or limit behavior of the FREQ according to the table in the RRULE specification.
Field "By week day" has two variants of the input: checkbox for each week day and text input. Text input can be used, if "By week day" value is more complex than just list of week days, separated by coma, for example for FREQ MONTHLY value "2TH,-3FR" in the "By week day" will mean second Thursday from the month start and third Friday from the month end in every month. Such value can’t be presented as checkboxes selection.
Fields "By set position" and "By year day" are text inputs. Value format for these fields is set of the [+/-]NUMBER values, separated by comma.
For the "By year day" minus sign in front of year day number means that this day should be taken by number from the end of the year.
For the "By set position" minus sign in front of the position of the iteration means that the iteration should be taken by number from the end of the generated iterations sequence.
After new event created, event will appear in time set event list. It will have column with rrule text description, buttons to request event edit form or event deletion.
In events list section all events can be redefined uploading ics iCalendar file:
If "Purge existing" option is selected, all existing time set events will be removed before creation of the events from the uploaded file.
To download iCalendar ics file of the time set, press "Download iCalendar".
Reseller details page provides list of the time sets connected to the reseller and allows create, edit, delete and download time set and has link to the time set events section:
In difference to the main time set interface, iCalendar ics file for the time set can be downloaded from the time set list pressing "Download" button.
Creation form doesn’t have "Reseller" field and is processed in context of the current reseller.
Time sets management is possible using API REST entry point /api/timesets/.
Time sets API has possibility to get and return information both as "application/json" data and as "text/calendar" file.
To create time set with events full specification of the all fields in json format can be used:
curl --request POST --user administrator:administrator --header Prefer: return=representation --header Content-Type: application/json https://127.0.0.1:1443/api/timesets/ --data {"reseller_id":"3", "name":"api_test_timeset_name1","times":[{"start":"1971-01-01 00:00:01","until":"1997-01-01 23:59:59","end":"2020-12-31 23:59:59"}]}
Also time set and events can be uploaded as ics iCalendar file:
curl --request POST --user administrator:administrator --header Prefer: return=representation --header Content-Type: multipart/form-data https://127.0.0.1:1443/api/timesets/ --form json={"reseller_id":3,"name":"unique_name"} --form calendarfile=@/path/to/calendar.ics
Output of the GET request to the time set item can be text/calendar:
curl --request GET --user administrator:administrator --header Accept: text/calendar https://127.0.0.1:1443/api/timesets/12 \> /path/to/download/calendar.ics
or application/json:
curl --request GET --user administrator:administrator --header Accept: application/json https://127.0.0.1:1443/api/timesets/12
By default API will send response in text/calendar format.
Output will be generated iCalendar including time set events:
curl --request GET --user administrator:administrator 'https://127.0.0.1:1443/api/timesets/12' BEGIN:VCALENDAR PRODID:-//Mozilla.org/NONSGML Mozilla Calendar V1.1//EN NAME:api_test_timeset_name2 VERSION:2.0 BEGIN:VEVENT UID:sipwise19@sipwise15 SUMMARY:unique_name event 19 DTSTART:19710101T000001 DTEND:20201231T235959 END:VEVENT END:VCALENDAR+