How to Develop a 3CX Plugin (2024)

Introduction

3CX can integrate with any CRM that has a REST API to match an email or a number to a customer account in your CRM, helpdesk or ticketing system.

To match caller IDs to customers when 3CX receives an inbound call, it queries the CRM system to look up the customer name. If found, the contact is added in 3CX Contacts, the caller name is displayed in the Web Client and the contact entry includes a link to open the CRM contact.

3CX supports a large number of CRMsout of the box. If your CRM is not in the list, you can easily create a template to integrate with your CRM using our CRM integration Wizard. You will need only basic coding / web skills and documentation of the REST API of your CRM.

This guide describes how to install and use the template generator tool, taking you through the required steps to create a new template for your CRM, based on an example 3CX CRM.

Step 1 - Obtain & Test REST API URls

First step is to obtain the necessary URLs and authentication method by searching the CRM / Helpdesk / Ticketing system website or contacting the vendor. Please make sure you have all the required documentation and ideally a support contact at the vendor if you have any questions. You will need:

• To find out whether your CRM supports “Basic” or“OAuth2” authentication.
• Whether authentication is via username and password or an API Key
• Web calls and responses for:

1. Contact lookup by phone number
2. Contact lookup by email
3. Contact search by any field (optional)
4. Contact creation (optional)
5. Call journaling (optional)
6. Chat journaling(optional)

Test the API calls with Postman!

Save time by testing these API calls first using the free Postman tool. The postman tool allows you to enter the URLs and see real time what the response will be. Postman has more debug tools than 3CX has so it's better to be sure about your API calls before you create and upload your integration.

Postman has some very good get started guides here.

Step 2 - Download the CRM integration Wizard

Download and install the 3CX CRM Integration Wizardfrom the Customer Portal. It walks you through the steps to createa template for 3CX. To create your CRM template:

1. Login to the Customer portal and download the Wizard.
2. Install the Wizard on a Windows Computer.
3. Launch the “3CX CRM Template Generator”, click on “File” > “New” > “CRM Template Wizard...” and click on “Next”.

Step 3 - Configure Authentication

1. Set a suitable “Template Name”.
2. Based on your CRM’s API documentation, set the authentication method to:

1. “None”
2. “Basic” and select to authenticate with:

1. “Username and Password”
2. “API Key”

3. “OAuth2” and set these:

1. “Authorization Endpoint” URL, e.g. https://api.example.com/oauth2/auth
2. “Token Endpoint” URL, e.g. https://api.example.com/oauth2/token
3. “Scope” - optional
4. “Additional Query String” - optional

4. Click “Next” to continue.

Step 4 - Configure contact lookup

Now you need to specify the API calls that need to be invoked in your CRM system in order to identify a customer. 3CX can search for contacts using the caller’s number for phone calls or SMS and Whatsapp messages, or the email address for Live Chat conversations.

1. “Lookup by Number API URL (GET)” - The URL to query the CRM for contacts based on their phone number.For example, for Freshdesk:

1. https://domain.freshdesk.com/api/v2/contacts?phone=[Number]

2. “Lookup by Email API URL (GET)” -The URL to query the CRM system based on their email address. For example, for Freshdesk:

1. https://domain.freshdesk.com/api/v2/contacts?email=[Email]

3. Click on “Next”.

Map the Contact Query Response to 3CX

1. Now we need to map the query response from your CRM to 3CX fields. To do this, you need to specify the path from the JSON response for each of the fields required by 3CX:

1. “Contact ID” - the ID of the matched contact, mandatory.
2. Set at least one of these fields:

1. “First Name”, e.g. contact.firstname
2. “Last Name”, e.g. contact.lastname
3. “CompanyName”, e.g. contact.company

3. “Email” - mandatory, e.g. contact.email
4. Click “Next” to proceed.

2. Now you need to map the respective response elements returned by the CRM web call, to at least one of these system variables:

1. “Business Phone”, e.g. contact.businessphone
2. “Business Phone 2”, e.g. contact.businessphone2
3. “Mobile Phone”, e.g. contact.mobilephone
4. “Mobile Phone 2”, e.g. contact.mobilephone2
5. “Custom Value” - optionally map a custom response element to a variable.
6. Set an appropriate “Contact URL” based on:
7. an expression, e.g. https://api.example.com/show?ContactID=[ContactID]
8. the server response, e.g. contact.profile_url
9. Click on “Next”.

Step 5 - Configure contact search

Now you need to specify the API calls that need to be invoked in your CRM system in order to search contacts by any field. This is used when the user searches contacts from the Web Client by phone number, email, name or company name.

1. “Search Contacts API URL (GET)” - The URL to query the CRM for contacts based on any field.For example, for Freshdesk:

1. https://domain.freshdesk.com/api/v2/contacts/autocomplete?term=[SearchText]

2. Click on “Next”.

Map the Contact Query Response to 3CX

1. Now we need to map the query response from your CRM to 3CX fields. To do this, you need to specify the path from the JSON response for each of the fields required by 3CX:

1. “Contact ID” - the ID of the matched contact, mandatory.
2. Set at least one of these fields:

1. “First Name”, e.g. contact.firstname
2. “Last Name”, e.g. contact.lastname
3. “CompanyName”, e.g. contact.company

3. “Email” - mandatory, e.g. contact.email
4. Click “Next” to proceed.

2. Now you need to map the respective response elements returned by the CRM web call, to at least one of these system variables:

1. “Business Phone”, e.g. contact.businessphone
2. “Business Phone 2”, e.g. contact.businessphone2
3. “Mobile Phone”, e.g. contact.mobilephone
4. “Mobile Phone 2”, e.g. contact.mobilephone2
5. “Custom Value” - optionally map a custom response element to a variable.
6. Set an appropriate “Contact URL” based on:
7. an expression, e.g. https://api.example.com/show?ContactID=[ContactID]
8. the server response, e.g. contact.profile_url
9. Click on “Next”.

Step 6 - Configure creating a customer in CRM

This is an optional step. If you want to enable the creation of a new contact in the CRM when the caller’s number can’t be matched to an existing customer, then enable the “Contact Creation” option. Configure:

1. The “API URL (POST)” - 3CX uses this URL to create a new contact in the CRM system.For example, for Freshdeskthis would be the API URL to use here:

1. https://domain.freshdesk.com/api/v2/contacts

2. “Request Data” - the data to send to the CRM in order to create the contact, e.g. {"firstname":"[FirstName]", "lastname":"[LastName]", "phone":"[Number]"}
3. Click “Next” to proceed.

Map the Contact Creation response

1. Now we need to map the query response from your CRM to 3CX fields. To do this, you need to specify the path from the JSON response for each of the fields required by 3CX:

1. “Contact ID” - the ID of the matched contact, mandatory.
2. Set at least one of these fields:

1. “First Name”, e.g. contact.firstname
2. “Last Name”, e.g. contact.lastname
3. “CompanyName”, e.g. contact.company

3. “Email” - set optionally, e.g. contact.email
4. Click “Next” to proceed.

2. Now you need to map the respective response elements returned by the CRM web call, to at least one of these system variables:

1. “Business Phone”, e.g. contact.businessphone
2. “Business Phone 2”, e.g. contact.businessphone2
3. “Mobile Phone”, e.g. contact.mobilephone
4. “Mobile Phone 2”, e.g. contact.mobilephone2
5. “Custom Value” - optionally map a custom response element to a variable.
6. Set an appropriate “Contact URL” based on:
7. an expression, e.g. https://api.example.com/show?ContactID=[ContactID]
8. the server response, e.g. contact.profile_url

3. Click on “Next”.

Step 7 - Configure call journaling

This is an optional step. If you want to journal calls as activities in the CRM, then enable the “Call Journaling” option.

1. “API URL (POST)” - 3CX uses this URL to create a new call activity in the CRM system.For example, for Freshdeskthis would be the API URL to use here:

https://domain.freshdesk.com/api/v2/tickets

2. Use the respective fields to define the data set to use for recording call journal entries for inbound answered and missed calls, and outbound answered and not answered calls.For example, for Freshdeskthis would be the JSON data to use here for inbound answered calls:

{"phone":"[Number]","description":"[InboundCallText]","requester_id":[EntityId],"subject":"[Subject]","type":"Question","status":2,"priority":1,"source":3}

3. Click “Next” to proceed.

Step 8 - Configure chat journaling

This is an optional step. If you want to register chat conversations as activities in the CRM, then enable the “Chat Journaling” option.

1. “API URL (POST)” - 3CX uses this URL to create a new chat activity in the CRM system.For example, for Freshdeskthis would be the API URL to use here:

https://domain.freshdesk.com/api/v2/tickets

2. “Request Data” - the data set to use for creating the chat journaling entries.For example, for Freshdeskthis would be the JSON data to use here:

{"phone":"[Number]","email":"[Email]","description":"[ChatMessages]","subject":"[ChatSubject]","requester_id":[EntityId],"type":"Question","status":2,"priority":1,"source":7}

3. Click “Next” to proceed.

Step 9 - Save & test the CRM integration

You reached the end of the wizard. Click on “Finish”, to save the generated CRM template and start testing it. You must check that all the URLs and JSON data entered during the wizard work as expected. The generated template contains some static parts, like the URLs or JSON data, and also variables that need to be set, like CRM credentials or descriptions to use when logging a call.

In order to fill these variables, expand the node with your template name in the tree view on the left, and click the “Parameter Values” node. A grid will be shown on the right, containing all the variables that can be set. Some variables will have default values (for example the text to use for call journaling), and others will be empty (for example your CRM credentials). These are the values that you will configure from the 3CX Management Console once you upload the template.

Testing Contact Lookup

When selecting the “Parameter Values” node, the Properties window under the tree view will show the values that you will use for testing. For example, there you can enter the phone number or email address from which you will trigger the contact lookup.

1. Select the Interaction Type (InboundCall, OutboundCall or Chat), and set the Number or Email to the value you want to search in the CRM.
2. Right click on the “Parameter Values” node and select “Contact Lookup By Number” or “Contact Lookup By Email”.

3. A new node with a date / time stamp is displayed under Parameter Values. Click on it to show the scenario result.
4. The Request/Response tab displays the request sent to the CRM and the JSON response received back. The Response Text shows that the number was mapped to a contact named “Joe Black”.

5. The Response Tree tab shows how the JSON response is mapped to 3CX variables. The variables in bold show that there was a match.
6. The Variables tab shows all the variables that were mapped during the contact lookup.
7. The Output tab shows the data returned to 3CX.
8. You can test contact search by any field, call journaling or chat journaling in the same way.

Step 10 - Upload the template to 3CX

Once the template has been tested and debugged, it’s time to upload it to 3CX. To do this, go to 3CX “Management Console”> “Settings”> “CRM”> “Server side”tab and click “Add”to upload your template to 3CX.

See Also

• Review the 3CX XML template descriptionfor a complete reference.

Last Updated

This document was last updated on 23 September 2023

https://www.3cx.com/docs/crm-integration/