IntroductionA.

B.

C.

Tribox

FreePBX

OpenCNAM Integration with Trixbox 2.8.0.4

OpenCNAM provides a Caller ID Lookup service that adds Caller ID Name to

inbound calls on PBX systems easily and economically. When a phone service

provider sends calls to the PBX with only a number as Caller ID, the number

can be looked up using the OpenCNAM service to get the correct Caller ID

Name. The Caller ID Name is attached to the incoming call before it is routed

to its destination in the PBX, so that it displays on phone calls and in call logs.

Trixbox is a PBX distribution that contains the Linux operating system, Asterisk

telephony engine, and the FreePBX web interface to configure it, among other

software. Trixbox versions supported include 2.6 and 2.8 versions.

Trixbox contains an embedded version of FreePBX, which provides

configuration of the PBX functions of Asterisk. Throughout these instructions,

FreePBX refers to this portion of Trixbox found under the PBX/PBX Settings

menu.

D. Operation

Configuration

FreePBX has two configurations involved in managing incoming calls, the

Trunk, and the Inbound Route. A third configuration then also defines Caller

ID Lookup Sources if that is configured by the Inbound Route. Calls flow from

the Trunk through the matching Inbound Route where the optional Caller ID

Name lookup happens, the new name replaces the original name value (only)

from the original call, and then is routed on to the destination specified in the

Inbound Route.

FreePBX has many types of configurable data, each on a pull down menu

from the FreePBX Administration page. The Trunk and Inbound Route

configurations are on the Connectivity pulldown menu. The Caller ID Lookup

Sources configuration is on the Admin menu. For each configuration, there

can be multiple records, each with different data.

TRUNK DESTINATIONINBOUND

ROUTECALL

LOOKUP

CALL

Editing Records The list of existing records is shown in a list on the right side, along

with an empty form to create a new record. When editing existing

information, be sure to select the original record from the list on

the right side rather than accidentally creating a new record. When

changes are complete, the Submit button at the end of the page

must be pressed to store the changes. In most cases, pressing

enter after changing a field will also activate the Submit button as a

convenient shortcut.

Quick-Start Guide

With Trixbox installed and operating normally, where inbound calls from

a Trunk are matched to one or more Inbound Routes and sent on to a

destination, these few simple steps will add OpenCNAM lookups to your calls.

Applying configuration

changes

When any record is saved, the menu bar shows a red Apply Config

button. This indicates that changes to the configuration have been

saved to the database storage, but not made active on the PBX as

yet. When a set of changes is complete, press the Apply Config

button to make the changes live before checking that the PBX now

operates as desired.

A. OpenCNAM Account

1

2

Log into an existing

http://www.opencnam.com

account or create a new one.

Then select the DASHBOARD to

view your account SID and Auth

Token. Both these values will be

needed later to enable OpenCNAM

lookups.

B. Caller ID Lookup Source

1

2

From the PBX/PBX Settings menu

of Trixbox, select Caller ID Lookup

Sources on the FreePBX menu.

If there is an existing OpenCNAM

option on the right side selector

list, select it to update the existing

record instead of creating a new

one. Otherwise, continue to add

a new record. Set the Source

Description to OpenCNAM, then

select HTTP for the Source Type.

4

5

Finally press Submit Changes to

save these settings.

The apply config button does not

need to be pressed now, as there

are more changes to make. Next,

select the Inbound Routes section

from the FreePBX menu.

3 Next set the following values for

the HTTP settings.

Make certain that there are no

spaces in these values, and that all

characters are exactly as shown.

In place of XXXX, substitute your

OpenCNAM account SID value.

In place of YYYY, substitute your

OpenCNAM auth token value.

Both are found on the OpenCNAM

dashboard as shown above.

Host:

Port:

Username:

Password:

Path:

Query:

api.opencnam.com

v3/phone/${Caller ID(num)}

account_sid=XXXX&auth_token=YYYY

At this point, the OpenCNAM service should be used to lookup CNAM for your

inbound calls that match this Inbound Route configuration. Refer to the

remainder of this documentation for further understanding and to resolve any

problems.

7 With the record selected, change the

CID Lookup Source to be OpenCNAM,

and make certain that an appropriate

destination is selected (such as an

extension). Then press the Submit

button.

After you press Submit, press the

Apply Configuration bar to make

these changes active.

6 If you already have an Incoming

Route created, select it from the

list of records on the right side.

Each one that you want to use

with OpenCNAM will need to be

changed this same way. If you do

not already have a record, create

an “any DID / any CID” record

by selecting Add Incoming Route

and leaving both DID and Caller ID

numbers blank.

Inbound Route

The Inbound Route contains

many configurable options, but

three in particular are necessary

to understand for OpenCNAM

operation. The CID and DID

numbers are used to match to

incoming calls. The CID number is

the Caller ID Number that the call

came from, and the DID is the Direct

Inward Dial number that the caller

dialed - i.e. your phone number.

B.

Trunk Context

Trunk

With a SIP or IAX2 trunk, it is possible to assign a context in the Peer

Details section (may be in a settings tab) of the Trunk configuration.

The context value controls how the incoming call is handled, and this

can be changed from the default value to enable the use of custom

call processing logic. It is best to not set the context and let FreePBX

use it’s default behavior, as a different context can prevent the

Caller ID lookup subroutine from functioning. However, if it is set, it

must be from-pstn, from-trunk, a custom context that includes

the ext-did context, or a custom context that calls the Caller ID

lookup subroutine directly. Those that understand Asterisk dialplan

configuration can consult the /etc/asterisk/extensions_additional.conf

file for details on contexts and cidlookup subroutine.

The Trunk is a definition of the connection between FreePBX and the phone

service provider of choice. This can be a SIP connection, IAX2, or DAHDi (used

for PRI and analog POTS hardware interfaces). There can be one or many

Trunks defined on a FreePBX system. The only requirement is that the Caller

ID Number is provided with each call. All inbound calls received over any

Trunk are then passed to the Inbound Route to determine which destination

they should be sent to, and optionally if Caller ID Name Lookup is to be

performed first.

A.

OpenCNAM Integration Reference

Caller ID Lookup Source selection in

Inbound Route

One of the configuration options in the Inbound Route is the CID

Lookup Source. This selects which one of the Caller ID Lookup

Sources (if any) will be used to lookup Caller ID Name from the

Caller ID Number. It may be located on the Other tab. This

value defaults to None, and must be changed to OpenCNAM (or

a different Caller ID Lookup Source record as needed) to enable

OpenCNAM. Make certain that each Inbound Route that OpenCNAM

is to be used with has the correct source selected.

Caller ID Lookup Sources

Caller ID Lookup Sources configures what source(s) can be used for lookups,

along with authorization codes and other configurable options as needed. Note

that defining a Caller ID Lookup Source alone does not cause it to be used.

The Caller ID Lookup Source must also be selected in the appropriate Inbound

Routes. When the system is installed, a single Caller ID Lookup Source with a

type of OpenCNAM should already be present, but must be edited to set the

account authorization for lookups.

The most common configurations are:

• A single default route (DID: ANY, CID: ANY) that matches all incoming calls

• A separate inbound route (DID: 1234567890, CID: ANY) for each DID

• A separate inbound route for some DIDs, and a default route for all others

Note that if route has both a DID and a CID number, both numbers must

match for that route to be used (this is not common and not recommended).

Also, be aware that if an incoming call does not match any inbound routes, the

call is refused.

C.

OpenCNAM Account

An account with OpenCNAM is required to perform Caller ID

Lookups, which is available for free by registering at https://www.opencnam.com/register. New registrations include over 100 free

queries.

Once registered, the dashboard shows the account balance, along

with the Account SID and Auth Token values that need to be

copied into the Caller ID Lookup Sources entry for OpenCNAM to

enable lookups. Press Show to view the Auth Token, but treat this

value like a password and don’t share it with anyone.

Review and Apply

At this point, it’s a good idea to go through the Inbound Routes and make sure

that all (or all that need OpenCNAM service) are set to use the OpenCNAM

record as the Caller ID Lookup Source. Then press the red Apply Changes button to cause these changes to be applied to the live running system.

Finally, make some calls into the system to check that the correct name is

appearing.

C.

Configuring OpenCNAM with

Authorization

A single Caller ID Lookup source named “OpenCNAM” most likely

already exists. If not, use the Admin Module as shown above to

Remove, and then reinstall the Caller ID Lookup Module to recreate

it (Note: this will erase other Caller ID Lookup configurations). If the

record already exists, press the pencil icon to edit the record.

The Source type must be set to OpenCNAM. The ability to

Cache Results is not supported with OpenCNAM and will be

ignored even if set. The Account SID and Auth Token values must

be copied exactly from the OpenCNAM website dashboard (the Auth

Token will not be **** as in the screenshot above, but will show

your real token string). Once these settings are correct, press the

Submit button.

Troubleshooting

If OpenCNAM does not appear to be working (the number is showing, not a

name or an error), check the following:

1. Confirm that there is no context in the peer settings of the Trunk that the

call arrives on.

2. Which Inbound Route will match the call? Check both the Inbound Route

that should match, and the default (Any/Any) route if you have one just

to be sure. Do the inbound route(s) have OpenCNAM set as the Caller ID

Lookup Source?

3. In Caller ID Lookup Sources, does the OpenCNAM record have a type of

OpenCNAM, and does it have an Account SID and Auth Token that match

the OpenCNAM Dashboard?

If the Caller ID Name is being changed to an Error or Unknown or similar

message for all numbers, check the following:

1. In the Inbound Route, temporarily change the Caller ID Lookup Source to

None and test again. If the Caller ID Name continues to show Unknown

or another message consistently, then the wrong name may actually be

coming from the service provider, and at the same time OpenCNAM is not

configured correctly to replace it. Refer to the troubleshooting checklist

above instead. Make certain to restore the Caller ID Source setting to

OpenCNAM.

2. In the Caller ID Source record for OpenCNAM, double check that the

Account SID and Auth Token values match exactly the values from the

OpenCNAM Dashboard.

3. In the OpenCNAM Dashboard, check that there is a positive balance.

If the issue persists, please contact OpenCNAM Support from the

OpenCNAM dashboard for further assistance. You may also call Support

during normal business hours at 1-888-315-TELO option 2 for support.