Facebook tracking pixel
Documentation
Resources
Integration Guides

Trixbox Integration Guide

Share:

Introduction

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

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.

FreePBX

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.

Operation

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.

Call Routing Graph

Configuration

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.

Editing RecordsThe 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.
Applying Configuration ChangesWhen 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.

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.

OpenCNAM Account

Elastix Login1. Log into your OpenCNAM account or create a new one.
FreePBX Register 22. On the main dashboard or Manage Account page, you can view your account SID and Auth Token. Both these values will be needed later to enable OpenCNAM lookups.

Caller ID Lookup Source

Trixbox 11. From the PBX/PBX Settings menu of Trixbox, select Caller ID Lookup Sources on the FreePBX menu.
Trixbox 2
Trixbox 32. 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.
Host:api.opencnam.com
Port:
Username:
Password:
Path:v3/phone/${Caller ID(num)}
Query:accountsid=XXXX&authtoken=YYYY
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.
Trixbox 4
Trixbox 54. Finally press Submit Changes to save these settings.
Trixbox 65. 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.
Trixbox 76. 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.
Trixbox 87. 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.

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.

OpenCNAM Integration Reference

Trunk

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.

Trunk ContextWith 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.

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.

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

Caller ID Lookup Source Selection in Inbound RouteOne 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.

OpenCNAM AccountAn 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. |

Configuring OpenCNAM with AuthorizationA 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.

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.

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.

Support / Assistance

We are happy to assist with your integration. Our team can be reached in any of the following ways:

Phone: +1-888-315-8356 (TELO) or +1-678-631-8356 (TELO)
Email: support@opencnam.com

Overview

OpenCNAM has several interfaces available through which customers may perform CNAM queries. This document details the system and method for querying OpenCNAM using a RESTful API and provides integration instructions for Trixbox. 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 Open CNAM 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.

Support / Assistance

We are happy to assist with your integration. Our team can be reached in any of the following ways:

Phone: +1-888-315-8356 (TELO) or +1-678-631-8356 (TELO)
Email: support@opencnam.com

Ready to integrate OpenCNAM?

GET STARTED Try it free! No card required.