OpenCNAM Integration with FreePBXA. Introduction B. Operation OpenCNAM Integration with FreePBX...
Transcript of OpenCNAM Integration with FreePBXA. Introduction B. Operation OpenCNAM Integration with FreePBX...
IntroductionA.
B. Operation
OpenCNAM Integrationwith FreePBX
OpenCNAM provides a Caller ID Lookup service that adds Caller ID Name to
inbound calls on FreePBX 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 FreePBX, so that it displays on phone calls and in
call logs.
FreePBX has two configurations involved in managing incoming calls, the
Trunk, and the Inbound Route. A third configuration then also defines CallerID
Lookup Sources if that is configured by the Inbound Route. Calls flow from the
Trunk through the matching Inbound Route where the optional CallerID Name
lookup happens, and then on to the destination.
TRUNK DESTINATIONINBOUND
ROUTECALL
LOOKUP
CALL
1
2
3
4
5
From the Admin pull down
menu, select Module Admin.
In the Admin section of
modules, find the CallerID
Lookup module and select it.
Select the action Download
and Install
Make certain that the Standard
and Extended repositories are
selected
Press Check Online
6 In the upper right corner of the
page, select Process
Installing the FreePBX CallerID Module
FreePBX has a flexible system of modules that provide additional features. These
can be downloaded online and added to your system using the Module Admin menu.
The CallerID Lookup Sources module that is used with OpenCNAM is most likely
already installed by default. Under the Admin menu, if there is option for “CallerID
Lookup Sources”, then the module is already installed. If not, go through the
following steps to install it:
C.
7
8
When it shows the module to be
installed, Press Confirm
After the installation completes,
Press Return
Editing Records
Configuration
In newer versions of FreePBX (13+) existing records are shown with a
pencil icon to edit them. There will also be a button to create new
records. In older versions of FreePBX, 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.
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 CallerID Lookup Sources
configuration is on the Admin menu. For each configuration, there can be
multiple records, each with different data.
Applying configuration
changes
Trunk Context
Trunk
Inbound Route
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.
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 callerid 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 callerid 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 CallerID Name Lookup is to be
performed first.
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.
D.
E.
(screenshot here)
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.
Lookup Source
Superfecta
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.
If the CID Superfecta module (an alternate CID Lookup method)
is installed, there will also be a Inbound Route configuration entry
Enable Superfecta Lookup. This must be set to No to prevent it
from interfering with OpenCNAM.
OpenCNAM Account
Caller ID Lookup Sources
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 a free credit.
Once registered, the dashboard shows the account balance, along
with the Account SID and Auth Token values that need to be copied
into FreePBX to enable lookups. Press Show to view the Auth
Token, but treat this value like a password and don’t share it with
anyone.
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.
F.
Configuring OpenCNAM with Authorization
Using multiple OpenCNAM accounts
A single CallerID Lookup source named “OpenCNAM” most likely
already exists. If not, use the Admin Module as shown above to
Remove, and then reinstall the CallerID Lookup Module to recreate
it (Note: this will erase other CallerID 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.
Unfortunately, this is not possible with the 13.0.10 version of the
Caller ID Lookup Sources module.
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 CallerID 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.
G.
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 CallerID
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 CallerID 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 CallerID Source setting to
OpenCNAM.
2. In the CallerID 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 for further assistance.