Latest revision as of 19:27, 7 August 2014

To a limited extent, X2Engine 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 X2Engine installation, and it is very useful in expediting the retrieval of customer data when taking a call.

Note, far more in terms of integration with Asterisk may be possible via the REST API. That would, however require custom coding by the implementer; no out-of-box solutions are yet included with X2Engine's source code.

What it does

A customer, whose phone number is saved in X2Engine, calls the organization. As soon as the call session is initiated with the VoIP system, the VoIP system makes a web request to X2Engine's web API with the caller ID. The call is then recorded, and shows up inside X2Engine, 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 X2Engine at the right time. The procedure for implementing this customization can vary widely between phone systems, 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 X2Engine 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 callX2Engine.php, is included in the X2Engine 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 X2Engine, which can be found in protected/models

All three of these files (callX2Engine.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 X2Engine. 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 X2Engine to use for API authentication, when necessary.

$userKey

The API key of the X2Engine 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 callX2Engine.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 callX2Engine.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 X2Engine.
[from-pstn-custom]
exten => _.,1,AGI(callX2Engine.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.