Slider 2TryLearn MoreSlash your Phone bills - Slider Image

Use SIP trunks, WebRTC & Apps

Slash your Phone Bill by 80%

Integrating a CRM with 3CX

On this topic:

Integrating a CRM with 3CX

Introduction

Prerequisites

Step 1 - Get the required API calls as URLs

Step 2 - Set the template properties

Step 3 - Obtain and configure the required Parameters

Step 4 - Configure Authentication

Step 5 - Configure the contact matching scenarios

Step 6 - Configure the Call Journaling scenario

Step 7 - Configure the Create Contact scenario

Step 8 - Testing your CRM

Step 9 - Generate the XML file

Introduction

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. If your CRM is not in the list, 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 you 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 Freshdesk.

Prerequisites

The CRM provider must have the following:

  • A RESTFul API with good documentation
  • The CRM must support Basic or OAuth2 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 and find the URLs for the API calls we will need:

  1. Authentication: we will use Basic Authentication as explained here.
  2. Sending a Contact query to perform the lookup:
    https://example.freshdesk.com/api/v2/contacts?phone=+15551234567

https://example.freshdesk.com/api/v2/contacts?mobile=+15551234567

  1. Sending a Create Ticket POST request to log calls as tickets:

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

  1. Sending a Create Contact POST request to automatically create contacts when not found:

https://example.freshdesk.com/api/v2/contacts

Step 2 - Set the template properties

Open the 3CX Template Generator tool. A new template empty will be automatically created. Select the “New Template” node and then fill the properties:

  • Country: this needs to be set to a 2 letters country code, for example: US
  • Name: set it to Freshdesk
  • Version: set it to 1
  • InternationalPrefix: set it to Zeros
  • MaxLength: leave it empty, so the number is sent to Freshdesk as it comes to 3CX

Step 3 - 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 Freshdesk are the following:

  • For Contact Lookup:
  • Click on Parameters > Add > Name = APIkey and Title = API Key: of type String
  • Click on Parameters > Add > Name = Domain and Title = Domain Part: of type String
  • For Call Journaling:
  • Click on Parameters > Add > Name = ReportCallEnabled and Title = Enable Call Journaling of type Boolean
  • Click on Parameters > Add > Name = Subject and Title = Ticket Subject: of type String
  • Click on Parameters > Add > Name = InboundCallText and Title = Answered Inbound Call: of type String
  • Click on Parameters > Add > Name = MissedCallText and Title = Missed Call: of type String
  • Click on Parameters > Add > Name = OutboundCallText and Title = Answered Outbound Call: of type String
  • Click on Parameters > Add > Name = NotAnweredOutboundCallText and Title = Unanswered Outbound Call: of type String
  • For Contact Creation:
  • Click on Parameters > Add > Name = CreateContactEnabled and Title = Enable Contact Creation of type Boolean
  • Click on Parameters > Add > Name = CreateContactName and Title = New Contact Name: of type String

Step 4 - Configure Authentication

We’re using Basic authentication here, so proceed as follows:

  • Click on Authentication
  • Select Type = Basic
  • In the Value field put the APIkey parameter variable: [APIkey]:X

Then, all the requests will be sent to the server including the Authorization header with the proper value for Basic authentication.

Step 5 - Configure the contact matching scenarios

Add a Scenario to perform the lookup by the phone field:

  • Click on Matching Scenario and set Request Type to Get
  • Enter the URL: https://[Domain].freshdesk.com/api/v2/contacts?phone=[Number]
  • Set the response type to JSON
  • Create a Rule Group with Path: phone and Type: Number. This will consider the path “phone” from the JSON response as a single record.
  • Add 5 variables
  • Key = Id and Path = id
  • Key = Name and Path = name
  • Key = WorkPhone and Path = phone
  • Key = MobilePhone and Path = mobile
  • Key = Email and Path = email
  • Add 6 outputs
  • Type = ContactId Value = [Id]
  • Type = FirstName Value = [Name]
  • Type = PhoneMobile Value = [MobilePhone]
  • Type = PhoneBusiness Value = [WorkPhone]
  • Type = Email Value = [Email]
  • Type = ContactUrl Value = https://[Domain].freshdesk.com/contacts/[Id]

Add another Scenario to perform the lookup by the mobile field:

  • Repeat the steps above, but enter the following URL instead: https://[Domain].freshdesk.com/api/v2/contacts?mobile=[Number]
  • And set the Rule Group with Path: mobile and Type: Number

Step 6 - Configure the Call Journaling scenario

Add a Scenario to create tickets in Freshdesk when a call ends:

  • Change the Scenario Id to ReportCall
  • In order to avoid the scenario execution when the feature is disabled, set the SkipIf expression to [ReportCallEnabled]!=True
  • Set Request Type to Post
  • Enter the URL: https://[Domain].freshdesk.com/api/v2/tickets
  • Set the request encoding type to JSON
  • Set the response type to JSON

Now we need to specify the Post data. This can’t be done from the tool, so save the changes, close the tool and open the template xml file using a text editor. Look for the Scenario element with Id=”ReportCall”, and edit it as follows:

<Scenario Id="ReportCall">

  <Request SkipIf="[ReportCallEnabled]!=True" Url="https://[Domain].freshdesk.com/api/v2/tickets" RequestType="Post" RequestEncoding="Json" ResponseType="Json" >

    <PostValues>

      <Value Key="requester_id" Type="Integer">[Contact::ContactId]</Value>

      <Value Key="phone">[Number]</Value>

      <Value Key="subject" Passes="2">[[Subject]]</Value>

      <Value Key="status" Type="Integer">2</Value>

      <Value Key="priority" Type="Integer">1</Value>

      <Value Key="description" Passes="2" If="[CallType]==Inbound">[[InboundCallText]]</Value>

      <Value Key="description" Passes="2" If="[CallType]==Missed">[[MissedCallText]]</Value>

      <Value Key="description" Passes="2" If="[CallType]==Outbound">[[OutboundCallText]]</Value>

      <Value Key="description" Passes="2" If="[CallType]==Notanswered">[[NotAnweredOutboundCallText]]</Value>

      <Value Key="source" Type="Integer">3</Value>

      <Array Key="tags">

        <Value>[CallType]</Value>

        <Value>Call</Value>

        <Value>[Agent]</Value>

      </Array>

    </PostValues>

  </Request>

</Scenario>

The XML structure inside the <PostValues> element will be converted to a JSON object, as follows:

{

  requester_id: 1234,

  phone: "+15551234567",

  subject: "New Ticket",

  status: 2,

  priority: 1,

  description: "03/12/2018: Answered incoming call from +15551234567 John Doe to 100 (5:32)",

  source: 3,

  tags: [

    "Inbound",

    "Call",

    "100"

  ]

}

Please note the following details:

  • The value used for requester_id is taken from the variable [Contact::ContactId]. You can use here any output value from the contact lookup.
  • The values “subject” and “description” have the attribute Passes="2", and double brackets in variables [[Subject]] and [[InboundCallText]]. That means that the expression needs to be evaluated twice. The first time, the engine will get the values from variables [Subject] and [InboundCallText], and then it will evaluate again what was returned by them. So, for example for the description:
  • First pass: [[InboundCallText]] >> [DateTime]: Answered incoming call from [Number] [Name] to [Agent] ([Duration])
  • Second pass: [DateTime]: Answered incoming call from [Number] [Name] to [Agent] ([Duration]) >> 03/12/2018: Answered incoming call from +15551234567 John Doe to 100 (5:32)
  • The value “description” is present 4 times. But the “If” attribute works as a selector, resulting in 3 of them not being generated as output.

Please note that this scenario doesn’t have any Variable or Output. This is because the ReportCall scenario doesn’t need to return any information to 3CX.

Save the changes to the XML and open the 3CX Template Generator tool.

Step 7 - Configure the Create Contact scenario

Add a Scenario to create contacts in Freshdesk when the caller number can’t be found:

  • Change the Scenario Id to CreateContactRecord
  • In order to avoid the scenario execution when the feature is disabled, set the SkipIf expression to [CreateContactEnabled]!=True
  • Set Request Type to Post
  • Enter the URL: https://[Domain].freshdesk.com/api/v2/contacts
  • Set the request encoding type to JSON
  • Set the response type to JSON

Now we need to specify the Post data. This can’t be done from the tool, so save the changes, close the tool and open the template xml file using a text editor. Look for the Scenario element with Id=”CreateContactRecord”, and edit it as follows:

<Scenario Id="CreateContactRecord">

  <Request SkipIf="[CreateContactEnabled]!=True" Url="https://[Domain].freshdesk.com/api/v2/contacts" RequestType="Post" RequestEncoding="Json" ResponseType="Json" >

    <PostValues>

      <Value Passes="2" Key="name">[[CreateContactName]]</Value>

      <Value Passes="1" Key="phone">[Number]</Value>

    </PostValues>

  </Request>

  <Rules>

    <Rule Type="Any">id</Rule>

  </Rules>

  <Variables>

    <Variable Name="Id" Path="id" />

  </Variables>

  <Outputs AllowEmpty="false">

    <Output Type="ContactUrl" Value="https://[Domain].freshdesk.com/contacts/[Id]" />

    <Output Type="FirstName" Value="[CreateContactName]" />

    <Output Type="PhoneBusiness" Value="[Number]" />

    <Output Type="ContactId" Value="[Id]" />

  </Outputs>

</Scenario>

The XML structure inside the <PostValues> element will be converted to a JSON object, as follows:

{

  name: "John Doe",

  phone: "+15551234567"

}

Please note the following details:

  • The value “name” has the attribute Passes="2", and double brackets in variable [[CreateContactName]]. That means that the expression needs to be evaluated twice. The first time, the engine will get the value from variable [CreateContactName], and then it will evaluate again what was returned by it. So, for example:
  • First pass: [[CreateContactName]] >> New 3CX Contact [Number]
  • Second pass: New 3CX Contact [Number] >> New 3CX Contact +15551234567

This scenario needs to return the contact details, in the same way that the lookup scenarios do. That means that we need to define rules, variables and output.

Save the changes to the XML and open the 3CX Template Generator tool.

Step 8 - 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 information to connect to your Freshdesk account:

  • 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 “Contact Lookup” 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 “Joe Black”.

  • The response tree shows the JSON response, and the scenario has a valid response.
  • The variables in bold show that there was a match.

In order to test the automatic Contact Creation, perform a lookup from a number you know is not in Freshdesk. In this case, the tool will automatically create a new contact when the lookup returns no data.

To test the Call Journaling feature, click on the Parameter Values node, and then fill in the Report Call section. That will emulate a call journaling request using the data provided.

Step 9 - Generate the XML file

  • Click on File > Save as and name the template Freshdesk.xml
  • Go to your 3CX Console > Settings > CRM Integration > Server side tab > and click Add to upload your template to 3CX.
  • 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.

Free for up to 1 year! Select preferred deployment:

On-Premise

for Linux on a $200 appliance or as a VM

Get the ISO

On-Premise

for Windows as a VM

Download the setup file

On the cloud

In your Google, Amazon, Azure account

Take the PBX Express