© 2015 X2Engine Inc.

Difference between revisions of "VoIP Integration"

From X2Engine
Jump to: navigation, search
(Using the included script for Asterisk integration)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Category:Development]]
 
[[Category:Development]]
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.
+
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 Reference|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 =
 
= 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 [[Remote_API#Inbound_VoIP_call_notifications|web API]] with the caller ID. The call is then recorded, and shows up inside X2CRM, in three places:  
+
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_Reference_%28Legacy%29#Inbound_VoIP_call_notifications|web API]] with the caller ID. The call is then recorded, and shows up inside X2Engine, in three places:  
 
# The activity feed, with a link to the contact;
 
# The activity feed, with a link to the contact;
 
# As a notification for the user who has been assigned that contact, or for all users if the contact is unassigned;
 
# As a notification for the user who has been assigned that contact, or for all users if the contact is unassigned;
Line 10: Line 12:
  
 
= What it requires in order to work =
 
= 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 <tt>GET</tt>) to X2CRM at the right time. How this will work in different phone systems can vary widely. How the essential API call must be made is described in [[Remote_API#Inbound_VoIP_call_notifications|Remote API: Inbound VoIP call notifications]].
+
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 <tt>GET</tt>) 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 [[Web_API_Reference_%28Legacy%29#Inbound_VoIP_call_notifications|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.
+
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 =
 
= Using the included script for Asterisk integration =
The script for Asterisk integration, named <tt>callX2CRM.php</tt>, is included in the X2CRM source code (in Professional Edition) inside the directory <tt>protected/integration/FreePBX</tt>. It requires the following two files be present in the same directory where it will be run:
+
The script for Asterisk integration, named <tt>callX2Engine.php</tt>, is included in the X2Engine source code (in Professional Edition) inside the directory <tt>protected/integration/FreePBX</tt>. It requires the following two files be present in the same directory where it will run:
 
# The [http://phpagi.sourceforge.net/ PHPAGI] class (and with the filename <tt>phpagi.php</tt>)
 
# The [http://phpagi.sourceforge.net/ PHPAGI] class (and with the filename <tt>phpagi.php</tt>)
# A copy of the standalone APIModel class from X2CRM, which can be found in <tt>protected/models</tt>
+
# A copy of the standalone APIModel class from X2Engine, which can be found in <tt>protected/models</tt>
  
All three of these files (<tt>callX2CRM.php</tt> and its dependencies) must then be placed in the <tt>agi-bin</tt> directory on the Asterisk server to allow easily inserting it as an application call into the dialplan.  
+
All three of these files (<tt>callX2Engine.php</tt> and its dependencies) must then be placed in the <tt>agi-bin</tt> 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:
 
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:
 
;<tt>$baseUrl</tt>
 
;<tt>$baseUrl</tt>
: The URL to the entry script (<tt>index.php</tt>) of X2CRM. For example, if your CRM is hosted in http://example.com/crm, you will put for the value of this variable <tt>http://example.com/crm/index.php</tt>.
+
: The URL to the entry script (<tt>index.php</tt>) of X2Engine. For example, if your CRM is hosted in http://example.com/crm, you will put for the value of this variable <tt>http://example.com/crm/index.php</tt>.
 
;<tt>$user</tt>
 
;<tt>$user</tt>
: The user of X2CRM to use for API authentication, when necessary.
+
: The user of X2Engine to use for API authentication, when necessary.
 
;<tt>$userKey</tt>
 
;<tt>$userKey</tt>
: The API key of the X2CRM user for API authentication.
+
: The API key of the X2Engine user for API authentication.
  
 
= Case example: FreePBX integration =
 
= Case example: FreePBX integration =
 
FreePBX can be configured to use the AGI script easily, by performing the following:
 
FreePBX can be configured to use the AGI script easily, by performing the following:
# Upload the dialplan file <tt>extensions_custom.conf</tt> (you'll find it in the same directory as <tt>callX2CRM.php</tt>) to replace the existing file in the Asterisk configuration directory on the phone system. In FreePBX distro, this directory will be <tt>/etc/asterisk</tt>.
+
# Upload the dialplan file <tt>extensions_custom.conf</tt> (you'll find it in the same directory as <tt>callX2Engine.php</tt>) to replace the existing file in the Asterisk configuration directory on the phone system. In FreePBX distro, this directory will be <tt>/etc/asterisk</tt>.
 
# As for the PHP scripts: the <tt>agi-bin</tt> directory, in FreePBX distro, is located at <tt>/var/lib/asterisk/agi-bin</tt>. Note, if using FreePBX distro, you should exclude <tt>phpagi.php</tt>, because it is already present and available in the <tt>agi-bin</tt> folder.
 
# As for the PHP scripts: the <tt>agi-bin</tt> directory, in FreePBX distro, is located at <tt>/var/lib/asterisk/agi-bin</tt>. Note, if using FreePBX distro, you should exclude <tt>phpagi.php</tt>, because it is already present and available in the <tt>agi-bin</tt> folder.
# Change the permissions on <tt>callX2CRM.php</tt> to be executable and readable by the system user <tt>asterisk</tt>.
+
# Change the permissions on <tt>callX2Engine.php</tt> to be executable and readable by the system user <tt>asterisk</tt>.
  
 
== What this all does ==
 
== What this all does ==
Line 39: Line 41:
 
<pre>
 
<pre>
 
;; This file can be put in /etc/asterisk to configure a FreePBX-managed Asterisk system for
 
;; This file can be put in /etc/asterisk to configure a FreePBX-managed Asterisk system for
;; creating inbound call notifications in X2CRM.
+
;; creating inbound call notifications in X2Engine.
 
[from-pstn-custom]
 
[from-pstn-custom]
exten => _.,1,AGI(callX2CRM.php)
+
exten => _.,1,AGI(callX2Engine.php)
 
</pre>
 
</pre>
 
When the file is included by in FreePBX's default dialplan file (<tt>extensions.conf</tt>), this <tt>[from-pstn-custom]</tt> context will be "imported" into the corresponding non-custom context, <tt>[from-pstn]</tt>. 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.
 
When the file is included by in FreePBX's default dialplan file (<tt>extensions.conf</tt>), this <tt>[from-pstn-custom]</tt> context will be "imported" into the corresponding non-custom context, <tt>[from-pstn]</tt>. 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.

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.