Revision as of 21:56, 31 December 2013

To a limited extent, X2CRM currently supports integration with VoIP phone systems (such as Asterisk servers) in the form of inbound call notifications and "screen pops". While this is still somewhat a proof-of-concept, setting it up to work is fully within the reach of the technically-inclined user with administrative access to the VoIP system and X2CRM installation, and it is very useful in expediting the retrieval of customer data when taking a call.

What it does

A customer, whose phone number is saved in X2CRM, calls the organization. As soon as the call session is initiated with the VoIP system, the VoIP system makes a web request to X2CRM's web API with the caller ID. The call is then recorded, and shows up inside X2CRM, in three places:

1. The activity feed, with a link to the contact;
2. As a notification for the user who has been assigned that contact, or for all users if the contact is unassigned;
3. In the action history on that contact record.

Additionally, if the contact is not assigned to "anyone", and the user to whom the contact is assigned does not have pop-up blocking enabled, a pop-up window will appear on the assignee's screen displaying the contact record, thus immediately displaying to that representative the full history of interaction with the customer.

What it requires in order to work

In essence, at the most basic level, the phone system must be connected to the internet, and must be configurable such that it makes an appropriate HTTP/HTTPS request (of type GET) to X2CRM at the right time. How this will work in different phone systems can vary widely, but how the essential API call must be made is the same in all cases and is described in Remote API: Inbound VoIP call notifications.

If the VoIP system is Asterisk-based, supports AGI interaction, and has PHP installed on it, a script included in the source code of X2CRM Professional Edition can be used instead of having to write a script from scratch. The rest of this article will cover the usage of this script.

Using the included script for Asterisk integration

The script for Asterisk integration, named callX2CRM.php, is included in the X2CRM source code (in Professional Edition) inside the directory protected/integration/FreePBX. It requires the following two files be present in the same directory where it will run:

1. The PHPAGI class (and with the filename phpagi.php)
2. A copy of the standalone APIModel class from X2CRM, which can be found in protected/models

All three of these files (callX2CRM.php and its dependencies) must then be placed in the agi-bin directory on the Asterisk server to allow easily inserting it as an application call into the dialplan.

Finally, the script itself must be configured appropriately. Near the top of the file, one will find the following global string variables that must be properly defined:

$baseUrl

The URL to the entry script (index.php) of X2CRM. For example, if your CRM is hosted in http://example.com/crm, you will put for the value of this variable http://example.com/crm/index.php.

$user

The user of X2CRM to use for API authentication, when necessary.

$userKey

The API key of the X2CRM user for API authentication.

Case example: FreePBX integration

FreePBX can be configured to use the AGI script easily, by performing the following:

1. Upload the dialplan file extensions_custom.conf (you'll find it in the same directory as callX2CRM.php) to replace the existing file in the Asterisk configuration directory on the phone system. In FreePBX distro, this directory will be /etc/asterisk.
2. As for the PHP scripts: the agi-bin directory, in FreePBX distro, is located at /var/lib/asterisk/agi-bin. Note, if using FreePBX distro, you should exclude phpagi.php, because it is already present and available in the agi-bin folder.
3. Change the permissions on callX2CRM.php to be executable and readable by the system user asterisk.

What this all does

The file extensions_custom.conf contains the following lines:

;; This file can be put in /etc/asterisk to configure a FreePBX-managed Asterisk system for
;; creating inbound call notifications in X2CRM.
[from-pstn-custom]
exten => _.,1,AGI(callX2CRM.php)

When the file is included by in FreePBX's default dialplan file (extensions.conf), this [from-pstn-custom] context will be "imported" into the corresponding non-custom context, [from-pstn]. This context is entered by callers coming in from the PSTN (Public Switched Telephone Network). Thus, putting the extension that makes the AGI call in from-pstn-custom will make it so that whenever a call comes in through the SIP trunk from a "traditional" phone network, the AGI call will be made.