3CX PBX in the Cloud
1 year FREE - no ties!
google cloud platform
Zero Admin
With the new Dashboard
Bulletproof Security
With SSL certs and NGINX
Install on $200 Appliance
Intel MiniPC architecture
New, Intuitive Windows Client
More themes, more UC
More CRM Integrations
Scripting Interface to add your own
Improved Integrated Web Conferencing
iOS and Android apps included
Run On-Premise or in the Cloud
Google, OVH, Windows & Linux
Fast & easy call management
With the 3CX Web Client

How to Develop a 3CX Plugin

Integrating a CRM with 3CX


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 ships with support for a large number of CRMs out of the box. However as there are many CRM, ERP and Accounting packages it is impossible for us 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 logon 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 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.

Step 1 - Get the required API calls as URLS

The three main functions of the CRM integration, require API calls as URLs for

  1. Authentatication https://login.salesforce.com/services/oauth2/token
  2. Contact matching
    [Url]/services/data/v37.0/search/?q=FIND {[Number]} IN PHONE FIELDS RETURNING Contact(Id,FirstName,LastName,AssistantPhone,Fax, HomePhone, MobilePhone, OtherPhone, Phone, Email,AccountId)
  3. Getting Account names: Some CRMS match a company using the same contact matching URL. In case this is not the case you must configured this URL separately Example
    [Url]/services/data/v37.0/query/?q=SELECT name from Account where Id = '[AccountId]'

Step 2 - Get 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 salesforce are these: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_understanding_username_password_oauth_flow.htm

In the case of salesforce we need the following parameters:

Click on Parameters > Add > Name = ClientId and Title = Consumer Key:

Click on Parameters > Add > Name = ClientSecret and Title = Consumer Secret:

Click on Parameters > Add > Name = UserName and Title = Username:

Click on Parameters > Add > Name = Password and Title = Password:

Click on Parameters > Add > Name = SecurityToken and Title = Security Token:

Step 3 - Configure Authentication

Create an Authentication Scenario: Click on Scenarios > Add > Set ID to Auth, Request Type = Post and enter URL: https://login.salesforce.com/services/oauth2/token 

Response Type = JSON

Create a Rule group and set Path to instance_url and Type to Any.

Add a variable with key = Url and Path = instance_url

Add a variable with key = AccessToken and Path = access_token

Add an Output of Type = Bearer and Value [AccessToken]

After click on the Authentication node and set Type = Scenario, in the Scenario section select the “Auth” Scenario from the dropdown.

Step 4 - Configure the contact matching scenario

Add a Scenario > Click on Matching Scenario and set Request Type to Get

Enter the URL: [Url]/services/data/v37.0/search/?q=FIND {[Number]} IN PHONE FIELDS RETURNING Contact(Id,FirstName,LastName,AssistantPhone,Fax, HomePhone, MobilePhone, OtherPhone, Phone, Email,AccountId)

Create a Rule Group with Path: searchRecords.Id and Type: Any

Add the variables required and the path from where to search for those records. Example:

Key = Id  Path = searchRecords.Id

Key = Phone  Path = searchRecords.Phone

Key = OtherPhone  Path = searchRecords.OtherPhone

Key = MobilePhone  Path = searchRecords.MobilePhone

Key = HomePhone  Path = searchRecords.HomePhone

Key = Fax  Path = searchRecords.Fax

Key = FirstName  Path = searchRecords.FirstName

Key = LastName  Path = searchRecords.LastName

Key = Email  Path = searchRecords.Email

Key = AcccountId  Path = searchRecords.AccountId

Step 5 - Testing your CRM

  1. In order to run this template from the tool, we need to set values for the input parameters. So we go to the Parameter Values node and fill both parameters with appropriate values:
  2. Set the phone number we need to emulate the call from, and set it to the Number property in the Property Editor:
  3. Finally, right click on the Parameter Values node and select Run to start the scenario execution. A new node will be added under Parameter Values, and clicking on it we can see the scenario execution results.
  4. When selecting the Request/Response tab, we can see the request and the JSON response containing some contacts data:

5. The response tree shows that each contact is located at the path “response.result.Contacts.row.FL”. There we have an array of items, and each of them is a field, for example the first name, the last name, phone numbers, etc. Let’s start adding variables for the data we need. For example, to add a variable for the First Name, we right click on the leaf node “content = ‘Test’”, and select Add Variable. We change the variable name to FirstName, because the default name will be “content” (the name of the node):

Go to the Template Tree, expand the Scenario and right click on Outputs. Add a new output, and it will be added as the final node. Edit it, changing the type to “ContactUrl”, and setting the value to the expression above.

If we run the template again, we will see that now all the required contact fields are present at the Output tab:

Step 6 - Generate the XML file

After you generate the xml file, you can now 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 come in, the incoming caller id number will be matched against the crm, and if a match is found, it will be displayed in the 3CX Webclient.

You might also be interested in: