the elastix call center protocol revealed
DESCRIPTION
Asterisk World, Thursday, January 30, 2014 ITEXPO EAST 2014 Miami USA Speaker: Eduardo SellanesTRANSCRIPT
Elastix Call Center ProtocolRevealed
Eduardo Sellanes January 28–31, 2014 | Miami Beach Convention Center
ECCP?
Elastix Call Center Protocol
Protocol developed by Elastix for the community
Goal?
• Allow client applications to communicate easily with a Call Center Server.
• Provide scalability and organization.
• Send asynchronous events.
Elastix…?
• Elastix is an Open Source Software to establish Unified Communications
It’s Free !!
Visit us!!!
Asterisk World Pavilion
What else do we need?
CallCenter Addon
• Installable from the Elastix Market Place
• > v2.0.0-14
It’s Free also !!
Install with a click
ECCP Architecture
ECCP SERVER
CLIENT APPLICATIONs
CLIENT APPLICATIONs
CLIENT APPLICATIONs
ECCP Architecture
Main service is called ‘dialerd’
ECCP SERVER
dialerd
ECCP Architecture
dialerd
→ /opt/elastix/dialer/dialerd
• daemon doesn’t execute as root user
[root@localhost dialer]#[root@localhost dialer]#[root@localhost dialer]#[root@localhost dialer]# cd /opt/elastix/dialer/[root@localhost dialer]# ./dialerd start
SECURITY WARNING: Sorry, I STRONGLY OBJECT to run as root.
This program requires only network access and therefore does not require root privileges.
[root@localhost dialer]#
ECCP Architecture
Start/Stop from Elastix Dashboard
ECCP Architecture
ECCP SERVER
dialerd
20005 CLIENT APPLICATIONs
Server is listening on port 20005
ECCP Architecture
ECCP SERVERdialerd
/opt/elastix/dialer/
php files
libs
ECCP Architecture
dialerd libs
[root@localhost dialer]# [root@localhost dialer]# ls *.phpAMIClientConn.class.php ECCPConn.class.phpMultiplexConn.class.phpAMIEventProcess.class.php ECCPProcess.class.php MultiplexServer.class.phpAbstractProcess.class.php ECCPServer.class.php Predictivo.class.phpAgente.class.php HubProcess.class.php TuberiaMensaje.class.phpAppLogger.class.php HubServer.class.php TuberiaProcess.class.phpCampaignProcess.class.php ListaAgentes.class.php phpagi.phpCampania.class.php ListaLlamadas.class.phpConfigDB.class.php Llamada.class.php[root@localhost dialer]# [root@localhost dialer]#
ECCP Architecture
ECCP SERVERdialerd
CallCenter Database
ECCP Architecture
Configuration file: → /opt/elastix/dialer/dialerd.conf
[database]# Credenciales para base de datos call_centerdbhost=localhostdbuser=asteriskdbpass=asterisk
(Credentials for database "call_center”)
ECCP Architecture
ECCP SERVERdialerd
Asterisk - AMI
ECCP Architecture
ECCP Architecture
ECCP SERVERdialerd
Logs files
ECCP Architecture
Logs file: → /opt/elastix/dialer/dialerd.log
logrotate configure file→ /etc/logrotate.d/elastixdialer
dialerd.log.1 dialerd.log.2..dialerd.log.5
Protocol
Simple – plain text
Based on XML (elements and attributes)
<event> <agentloggedin> <agent>Agent/9000</agent> <queues> <queue>8001</queue> <queue>8000</queue> </queues> </agentloggedin></event>
Protocol
Session oriented
Listen to multiple clients at the same time
• Client login (user/secret), Server create session• Client logout, Server destroy session• Timeout (5minutes), Server destroy session
Protocol
Three kinds of information packets
• Event
• Request
• Response
Each one is a well formed XML document
Protocol
Events
• Generated asynchronously from the server-side
<event>…</event>
Protocol
Events
<event> <agentloggedin> <agent>Agent/9000</agent> <queues> <queue>8001</queue> <queue>8000</queue> </queues> </agentloggedin></event>
Protocol
Requests
Message sent from the client to the server
<request id="identificador">...</request>
id identify each requestid = ‘timestamp LINUX‘ ‘dot’ ‘6 char random number’
id = 1292899827.123456
Protocol
Responses
Server response based on a client's previous requirement
<response id="identificador" >...</response>
response id is the same as request id
Protocol
CLIENTAPPLICATION
SERVER
request id=“x"
response id=“x"
response id=“x"
Request - Responses
Protocol
<request id="1292899827.123456">...</request>
<response id="1292899827.123456">...</response>
<response id="1292899827.123456">...</response>
Request - Responses
Protocol
<request id="1292899827.123456"> <getagentstatus> <agent_number>Agent/9000</agent_number> </getagentstatus></request >
<response id="1292899827.123456"> <getagentstatus_response> <status>offline</status> </getagentstatus_response></response>
Request - Responses
Protocol
<response id="identificador"> <failure> <code>XXX</code> <message>Error message</message> </failure></response>
An error is a response with failure element
Error Responses
Protocol
Protocol Error:
< response id="identificador"> < failure > <code>XXX</code> <message>Error messages</message> </ failure ></ response >
Error type
Protocol
Error at processing time:
< response id="identificador"> < failure > <request_response>
<code>XXX</code> <message>Error messages</message>
</request_response > </ failure ></ response >
Error type
Protocol
<response id="1292899827.123456"> <failure> <code>401</code> <message>Unauthorized</message> </failure></response>
<response id="1292899827.123456"> <login_response> <failure> <code>401</code> <message>Invalid username or password </message> </failure> </login_response ></response>
Error Samples
Protocol
Complete list of requests-response-events-error :
→ /opt/elastix/dialer/Protocolo ECCP.txt
Source code
→ /opt/elastix/dialer/dialerd → /opt/elastix/dialer/*.php (libs)
It’s OPENSOURCE !!
Create agent login/logout application
Application
We need…
ECCP user/secret - server connection
Agent user/secret - queue login
ApplicationECCP user/secret
ApplicationECCP user/secret
ApplicationAGENT user/secret
ApplicationAGENT user/secret
ApplicationLogin request
• Authenticate a client application
• Establish a session
Application
<request id="1292899827.123456"> <login> <username>userECCP</username> <password>secretECCP</password> </login></request>
ECCP Login request :
Application
<response id="1292899827.123456"> <login_response> <success/><app_cookie>35d290884ef77a78cc6c0006b7e1d576</app_cookie> </login_response></response>
<response id="1292899827.123456"> <login_response> <failure> <code>401</code> <message>Invalid username or password</message> </failure> </login_response></response>
OK response :
Fail response :
Application
<request id="1292899827.123456"> <loginagent> <agent_number>Agent/9000</agent_number> <agent_hash>XXXXXXXXXXXXXXXXXXXXXXXXX</agent_hash> <extension>1064</extension> </loginagent></request>
<response id="1292899827.123456"> <loginagent_response> <status>logging</status> </loginagent_response></response>
AGENT Queue Login request :
Application
CLIENTAPPLICATION
SERVER
login request
response “app_cookie”
CLIENTAPPLICATION
SERVERloginagent request
agent_hash
app_cookie - agent_hash
Application
<response id="1292899827.123456"> <login_response> <success/><app_cookie>35d290884ef77a78cc6c0006b7e1d576</app_cookie> </login_response></response>
<request id="1292899827.123456"> <loginagent> <agent_number>Agent/9000</agent_number> <agent_hash>XXXXXXXXXXXXXXXXXXXXXXXXX</agent_hash> <extension>1064</extension> </loginagent></request>
app_cookie - agent_hash
Applicationapp_cookie - agent_hash
s = app_cookie + "Agent/9000" + "AgentSecret“
agent_hash = MD5(s)
+ implies concatenate
Application
<request id="1292899827.123456"> <logoutagent> <agent_number>Agent/9000</agent_number> <agent_hash>XXXXXXXXXXXXXXXXXXXXXXXXX</agent_hash> </logoutagent></request>
<response id="1292899827.123456"> < logoutagent_response> <status>logged-out</status> </logoutagent_response></response>
AGENT Queue Logout request :
Application
<request id="1292899827.123456"><logout></logout>
</request>
<response id="1292899827.123456"> <logout_response>
<success/></logout_response>
</response>
ECCP Logout request :
Do we have to parse XML every time?
The answer is …
NO, of course…
Elastix does it for us
ECCP.class
/var/www/html/modules/agent_console/libs/ECCP.class.php
Take a look, read it, use it
It’s OPENSOURCE !!
How we use it?
It’s a class!!,
#!/usr/bin/php<?php
require_once("libs/ECCP.class.php");
$obj = new ECCP();
#!/usr/bin/php<?php
require_once("libs/ECCP.class.php");
$obj = new ECCP();
$host = “Elastix_Server_IP";$eccp_user = "ECCP_user";$eccp_pass = "ECCP_pass";
$agent = "Agent/9000";$agent_pass = "secret";$agent_extension = "2120";
print "Connecting.....\n";//try
$obj->connect($host, $eccp_user, $eccp_pass);
obj->setAgentNumber($agent);obj->setAgentPass($eccp_pass);
$ag_obj = $obj->loginagent($agent_extension);
//check if login ok? Failure?
print "Disconnecting...\n";$obj->disconnect();
//error?>
Download a complete example from:
http://elx.ec/eccpexample
What else?
Call Center PRO
Call Center PRO
Call Center PRO
Available Soon
Smart Assistant
Worldwide release19th of February, 2014
[email protected] @elastixworld-
disconnect()