This module allows real-time queries against the libphonenumber to be performed from the config script. With that it is possible to get normalize and get details about a phone number.

More details about libphonenumber can be found at https://github.com/googlei18n/libphonenumber.

This module exports a new class of pseudo-variables - $phn(pvc=>key) - to enable access to the results of a query to the database.

Many queries can be done and store results in different containers to be able to use in parallel.

2. Dependencies

2.1. Kamailio Modules

The following modules must be loaded before this module:

none.

2.2. External Libraries or Applications

The following libraries or applications must be installed before running Kamailio with this module loaded:

libphonenumber - the phone number library.

3. Parameters

3.1. `smode` (int)

Phone number search mode (not in use yet).

Default value is “0”.

Example 1.1. Set smode parameter

...
modparam("phonenum", "smode", 0)
...

3.2. `resid` (str)

Preregister result container id during initialization, enabling the use of the module in KEMI scripts. In native Kamailio.cfg file, registration is done when parsing config and finding variables.

Default value is “” (empty).

Example 1.2. Set resid parameter

...
modparam("phonenum", "resid", "src")
...
if(phonenum_match("1-484-555-8888", "src")) {
   ...
}
...

4. Functions

4.1. `phonenum_match(num, pvc)`

Match num against the libphonenumber and set the attributes inside the pvc result container. The function has to be called before accessing a key via: $phn(pvc=>key).

The parameters can be static strings or strings with variables.

It can be used from ANY_ROUTE.

Example 1.3. phonenum_match usage

...
if(phonenum_match("1-484-555-8888", "src")) {
    if($phn(src=>valid)==1) {
        xlog("number normalized to: $phn(src=>normalized)\n");
    } else {
        xlog("number normalization error: $phn(src=>error)\n");
    }
}
...

4.2. `phonenum_match_cn(num, cnc, pvc)`

Match num against the libphonenumber and set the attributes inside the pvc container, restricting the rules with a country name code (two letter, e.g: "DE", "US", "ES"). The function has to be called before accessing a key via: $phn(pvc=>key).

Note from libphonenumber library docs: country name code is the region that is expected the number to be from. It is only used if the number being parsed is not written in international format. The country code for the number in this case would be stored as that of the region supplied. If the number is guaranteed to start with a '+' followed by the country calling code, then region 'ZZ'.

The parameters can be static strings or strings with variables.

It can be used from ANY_ROUTE.

Example 1.4. phonenum_match_cn usage

...
if(phonenum_match_cn("1-484-555-8888", "US", "src")) {
    if($phn(src=>valid)==1) {
        xlog("number normalized to: $phn(src=>normalized)\n");
    } else {
        xlog("number normalization error: $phn(src=>error)\n");
    }
}
...

5. Pseudo Variables

$phn(pvc=>key) - pvc is an identifier for this query result; it is designated by the second parameter of phonenum_match(). The key can be one of the following:
- number - phone number that is matched
- valid - 1 if the matched number has a valid result; 0 otherwise
- normalized - normalized phone number
- cctel - country code for phone number
- ccname - country code name
- ltype - local network type
- ndesc - phone number description
- error - error string if phone number matching fails.

Exported pseudo-variables are documented at https://www.kamailio.org/wikidocs/.

PHONENUM Module

Daniel-Constantin Mierla

Edited by

Daniel-Constantin Mierla

Chapter 1. Admin Guide

1. Overview