IntroductionA.
B.
C.
Elastix
FreePBX
OpenCNAM Integrationwith Elastix 4.0
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.
Elastix is a PBX distribution that contains the Linux operating system, Asterisk
telephony engine, and the FreePBX web interface to configure it, among other
software. Elastix versions supported include 4.0 and all 2.X versions. Version
3.0 is not supported by OpenCNAM. The following instructions show images
of the 4.0 version, but the process is the same in 2.X.
Elastix contains an embedded version of FreePBX, which provides configuration
of the PBX functions of Asterisk. Throughout these instructions, FreePBX
refers to this portion of Elastix found under the PBX Configuration menu.
The step by step instructions and screenshots have been updated to match
Elastix.
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 are 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 Elastix 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 Configuration menu
of Elastix, select Caller ID Lookup
Sources on the FreePBX menu.
Then on the right side record
selector list, choose OpenCNAM.
4
5
6
Copy and paste the SID and Token
from your OpenCNAM dashboard.
Then press Submit to save the
record.
The apply config button does not
need to be pressed now, as there
are more changes to make. Select
the Inbound Routes section from the
FreePBX menu.
3 Next select the Professional Tier
checkbox.
9
10
Then press the Submit button.
Now press the Apply Configuration
bar to make these changes active.
8 With the record selected, change the
CID Lookup Source to be OpenCNAM.
7 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.
Trunk Context
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
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.
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.
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.
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.
B.
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.
D.
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.
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.
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.
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 CallerID 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.
Finally, make some calls into the system to check that the correct name is
appearing.