Integrating a CRM with 3CX
On this topic:
3CX includes a server side CRM integration which allows caller IDs to be matched to customers. When 3CX receives an inbound call, 3CX will query the CRM system, look up the customer name and if found, the contact will be added to the 3CX Contacts, and the caller name will be shown. In the web client it will also show a contact icon with a link to open the contact in your CRM.
3CX offers support for a large number of CRMs out of the box. However, as there are many CRMs, ERP and Accounting packages it is impossible for 3CX to support all of them. Rather, we have created a system that allows someone with basic coding / web skills to easily create a template / configuration for any REST based CRM/ERP system and import that into 3CX.
The system is a server side integration engine that takes an XML configuration file. These templates/configuration files define the authentication methods, the URLs to login to the system and the URLs and steps necessary to query contacts.
In this guide we will show how to install and use the template generator tool, and take you through the steps required to create a new template for your CRM. The CRM Selected is opencnam.
The CRM provider must have the following:
- A RESTFul API with good documentation
- The CRM must support Basic or oAuth modes of authentication
- Download the 3CX Template Generator from here.
- For a complete reference on the 3CX XML template description click here.
Step 1 - Get the required API calls as URLS
Access the API documentation of the CRM https://www.opencnam.com/developer/documentation and find the URLs for the 3 API calls we will need
- Authentatication https://api.opencnam.com/v3/phone/+16786318356?account_sid=SID&auth_token=TOKEN
- Sending a Contact query to perform the lookup
- Parse the response json data returned by the crm
Step 2 - Obtain and configure the required Parameters
Parameters are what the CRM will need as inputs from the user in order to construct the messages. The parameters for opencnam are the following:
- Click on Parameters > Add > Name = SID and Title = Account SID: of type String
- Click on Parameters > Add > Name = AuthToken and Title = Auth Token: of type String
- Click on Parameters > Add > Name = Casing and Title = Casing (caps or title): of type String
- Click on Parameters > Add > Name = Mobile and Title = Mobile (location or wireless): of type String
Step 3 - Configure Authentication
Create an Authentication Scenario:
- Click on Authentication
- In the Value field put these 2 parameter variables [SID]:[AuthToken]
- Type = Basic
- Scenario = [SID]:[AuthToken]
Step 4 - Configure the contact matching scenario
Add a Scenario:
- Click on Matching Scenario and set Request Type to Get
- Enter the URL: https://api.opencnam.com/v3/phone/[Number]?format=json&casing=[Casing]&mobile=[Mobile]&no_value=blank
- Set the response type to JSON
- Create a Rule Group with Path: name and Type: Any
- Add 2 variables
- Key = PhoneBusiness and Path = number
- Key = LastName and Path = name
- Add 3 outputs
- Type = PhoneBusiness Value = [PhoneBusiness]
- Type = LastName Value = [LastName]
- Type = ContactUrl Value = https://www.opencnam.com/
Step 5 - Testing your CRM
The tool allows you to test your CRM on the fly by adding the CRM’s values in the Parameter values section. Click on “Parameter Values” and use the examples provided in the API:
- SID: Enter your SID here example AC5190fff595933dff858dab0c84b5664c
- Auth Token: AU19a45fe61d3e99a0a1c65996a9918ee0
- Casing: title
- Mobile: location
- Set the phone number needed to emulate the call from, and set it to the Number property in the Property Editor:
- Right click on the Parameter Values node and select Run to start the scenario execution.
- A new node with a date / time stamp will be displayed under Parameter Values. Clicking on it will show the scenario result.
- The Request/Response tabs will display the request sent to the crm and it’s equivalent JSON response.
- The Response Text shows that the number was mapped to a contact named “SAMPLE”.
- The response tree shows the JSON response and the scenario has a valid response.
- The variables in bold show that there was a match.
Step 6 - Generate the XML file
- Click on File > Save as and name the template opencnam.xml
- Go to your 3CX Installation and copy the template in the following location.
- On Windows copy the file here: C:ProgramData3CXInstance1DataHttpTemplatescrm
- On Linux: /var/lib/3cxpbx/Instance1/Data/Http/Templates/crm
- Restart the 3CX Management console services and System service.
- When incoming calls occur, the incoming caller ID number will be queried against the CRM, and if a match is found, it will be displayed in the 3CX web client.