the elastix call center protocol revealed

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.

What do we need?

Elastix

• Download from www.elastix.org

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

info@elastixworld.com @elastixworld-

disconnect()