Call-Center Module

Each entity has a corresponding table in the database, for provisioning purposes - the cc_flows and cc_agents tables, see DB schema. Data is loaded at startup and cached into memory ; runtime reload is possible via the MI commands (see the cc_reload command in Exported MI Functions).

Additionally there is a table cc_cdrs for writing the CDRs - this operation is done in realtime, after the call in completed, covering all possible cases: call was dropped while in queue, call was rejected by agent, call was accepted by agent, call terminated with error - NOTE that a call may generate more than one CDR (like call rejected by agent A, and redistributed and accepted by agent B).

The cc_calls table is used to store ongoing calls, regardless it's state (in queue, to the agent, ended). It is populated at runtime by the module and queried at startup. This table should not be manually provisioned.

A flow is defined by a unique alphanumerical ID - the main attribute of a flow is the skill - the skill is a capability required by the flow for an agent to be able to answer the call ; the concept of skills is the link between the flows and the agents - telling what agents are serving what flows - the flows require a skill, while the agents provide a set of skills. Agents matching the required skill of a flow will automatically receive calls from that flow.

Additional, the flow has a priority - as agents may server multiple flows in the same time (based on skills), you can define priorities between the flows - if the flows has a higher priority, its calls will be pushed (in deliver to agents and queuing) in front of the calls from flows with a lower priority.

Optionally, the flow may define a prependcid - a prefix to be added to the CLI (Caller ID) when the call is delivered to the agents - as an agent may receive call from multiple flows, it is important for the user to see which was the queue a call was received.

In terms of media announcements, the flow defines the message_welcome (optional, to be played in the call, before doing anything with the call) and message_queue (mandatory, the looping message providing infinite on hold media IMPORTANT - this message must cycle and media server must never hung up on it. Both announcements are provided as SIP URIs (where the call has to be sent in order to get the playback).

An agent is defined by a unique alphanumerical ID - the main attribute of an agent is its the set of skills and its SIP location. The set of skills will tell what calls to be received (from which flows, based on the skill matching); the location is a SIP URI where to call must be sent in order to be answered by the agent.

Additionally, the agent has a initial logstate - if he is logged in or not (being logged in is a must in order to receive calls). The log state may be changed at runtime via a dedicated MI command cc_agent_login, see Exported MI Functions.

There is a wrapup_time defined, saying the time interval for an agent before getting a new call from the system (after he finished a call).

The following modules must be loaded before this module:

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

SQL address to the DB server -- database specific. This must be the Database holding the provisioning tables (cc_flows, cc_agents and cc_calls tables).

...
modparam("call_center", "db_url", 
	"mysql://opensips:opensipsrw@localhost/opensips")
...

SQL address to the DB server -- database specific. This must be the Database where the CDRs table (cc_cdrs) is located.

...
modparam("call_center", "acc_db_url", 
	"mysql://opensips:opensipsrw@localhost/opensips_cdrs")
...

The name of the B2B scenario that is used by the module for handling the calls in the queue. This is an advanced options and you should not change it unless you really understand what you are doing.

The module provides an B2B scenario file scenario_callcenter.xml located in the module directory. The name of this scenario from this file (which must be loaded via the b2b_logic module) must match the b2b_scenario parameter.

Default value is “call center”.

...
modparam("b2b_logic", "script_scenario", "/etc/opensips/scenario_callcenter.xml")
modparam("call_center", "b2b_scenario", "call center")
...

Time for an agent between finishing a call and receiving the next call from the system. Even if there are queued calls, the module will not deliver call to agent during this wrapup interval.

Default value is “30 seconds”.

...
modparam("call_center", "wrapup_time", 45)
...

The name of an SIP URI parameter to be used to report the position in the waiting queue when sending the call to media server for onwait/queue playback. The position 0 means it is the next call to be delivered to an agent.

Default value is “empty(none)”.

...
modparam("call_center", "queue_pos_param", "cc_pos")
...

This must be used only for initial INVITE requests - the function pushes the call to be handled by the call center module (via a certain flow/queue).

This function can be used from REQUEST_ROUTE.

The flowID mandatory parameter is the ID of the flow to handle this call (push the call to that flow). This can be a variable or a static string.

The function returns TRUE back to the script if the call was successfully pushed and handled by the Call Center engine. IMPORTANT: you must not do any signaling on the call (reply, relay) after this point.

In case of error, FALSE is returned to the script with the following return codes:

...
if (is_method("INVITE") and !has_totag()) {
	if (!cc_handle_call("tech_support")) {
		send_reply("403","Cannot handle call");
		exit;
	}
}
...

This function sets the login (on or off) state for an agent.

This function can be used from REQUEST_ROUTE.

The agentID mandatory parameter is the ID of the agent and the state is an integer value giving the new state - 0 means logged off, anything else means logged in.

...
# log off the 'agentX' agent
cc_agent_login("agentX","0");
...

Command to reload flows and agents definition from database.

It takes no parameter.

MI FIFO Command usage:

opensipsctl fifo cc_reload

Command to login an agent into the Call Center engine.

It takes two mandatory parameters, the ID of the agent and the new login state (0 - log off, 1 - log in)

MI FIFO Command usage:

opensipsctl fifo cc_agent_login agentX 0

Command to list all the calls in queuing - for each call, the following attributes will be printed: the flow of the call, for how long the call is in the queue, the ETW for the call, call priority and the call skill (inherited from the flow).

It takes no parameter.

MI FIFO Command usage:

opensipsctl fifo cc_list_queue

Command to list all the flows - for each flow, the following attributes will be printed: the flow ID, the avg. call duration, how many calls were processed, how many agents are logged, and how many onging calls are.

It takes no parameter.

MI FIFO Command usage:

opensipsctl fifo cc_list_flows

Command to list all the agents - for each agent, the following attributes will be printed: agent ID, agent login state and agent state (free, wrapup, incall).

It takes no parameter.

MI FIFO Command usage:

opensipsctl fifo cc_list_agents

Command to list all the ongoing calls - for each call, the following attributes will be printed: call ID, call state (welcome, queued, toagent, ended), call duration, flow it belongs to, agent serving the call (if any).

It takes no parameter.

MI FIFO Command usage:

opensipsctl fifo cc_list_agents

Command to reset all counter-like statistics.

It takes no parameter.

MI FIFO Command usage:

opensipsctl fifo cc_reset_stats