Solution Architecture - CX Campaigns

This document outlines the solution architecture for CX Campaigns.

Solution Components

The solution is comprised of the following main components,

Campaign Manager Front-end
Scheduler
Customer Channel Manager (CCM)
Voice Connector (VC)/ other channel connectors
EF CC Dialer/ Cisco Dialer / Channel Providers
Campaigns Database

Solution Workflow

Solution workflow for different channels.

Agent Based Calls

The campaign manager send a list of contacts with a scheduled call time to the scheduler.
The scheduler sends these contacts to the Customer Channel Manager(CCM) at the scheduled time.
The CCM passes these contacts to the voice connector(VC).
The VC sends these to the dialer.
The dialer stores them in the a database.
The dialer periodically reads this database and processes the contacts based on the campaign type.
For Agent-Based calls, the dialer sends an agent request to the VC.
The voice connector sends a request for a voice agent with the call details to the CCM.
The CCM obtains the details of an available Voice agent and send them to the VC.
The VC passes these details to the dialer.
The dialer sends a command to EFSwitch with the customer and agent information.
EFSwitch calls the customer.
Upon answer, the call is bridged to the EF CX Agent.
When the call ends the call result is sent to dialer via EFSwitch.
The call result is stored in the database and sent to the VC.
The VC sends this result to the CCM as a Delivery Notification.

IVR Based Calls

The campaign manager send a list of contacts with a scheduled call time to the scheduler.
The scheduler sends these contacts to the Customer Channel Manager(CCM) at the scheduled time.
The CCM passes these contacts to the voice connector(VC).
The VC sends these to the dialer.
The dialer stores them in the a database.
The dialer periodically reads this database and processes the contacts based on the campaign type.
The dialer sends a command to EFSwitch with the customer and IVR information.
EFSwitch calls the customer.
Upon answer, the call is bridged to the EFSwitch IVR.
When the call ends the call result is sent to dialer via EFSwitch.
The call result is stored in the database and sent to the VC.
The VC sends this result to the CCM as a Delivery Notification.

Digital Campaigns

Campaign Manager schedules an activity by calling exposed scheduler APIs
Scheduler pushes the scheduled activity to CX Activity to be part of customer history.
Scheduler Queues the activity and pushes it to CCM when the scheduled date time reaches.
CCM acts as a proxy and forwards the scheduled message to the relevant connector.
When the message is delivered, CCM sends back a delivery notification to the Scheduler that it received from the relevant connectors
Scheduler updates the delivery notification to CX Activities
Scheduler also pushes it to the Campaign Manager via registered webhooks.
When the customer reads the message or replies back to the scheduled message, CCM sends the delivery notification as READ. In addition, it also sends back the customer response received from connectors to Scheduler.
Scheduler pushes the READ delivery notification as well as the customer responses of the scheduled activity to CX Activities.
Scheduler also publishes the delivery notifications and customer response to the Campaign Manager via the registered webhooks.

Scheduler Diagram.drawio.png

Technical Solution

Contact Structure

The parameters for a campaign contact are set in the campaign manager sent to the scheduler.

These parameters are described in the following sections, along with other relevant information that the dialer stores in a database based on the state of the contact.

Mandatory

Field	Description	Type	Provided By
id	Unique UUID identifier used to identify this contact and call	VARCHAR(40)	Campaign Manager
customer_number	The number to be dialed	VARCHAR(20)	Campaign Manager
campaign_type	IVR or AGENT	VARCHAR(20)	Campaign Manager
gateway_id	The UUID of the EFSwitch gateway to be used to dial customer number	VARCHAR(40)	Campaign Manager
status	pending, agent_pending, dialed, ended, stopped or failed	VARCHAR(20)	Dialer
call_result	The result of a call e.g. Normal clearing, User busy etc	VARCHAR(40)	Dialer
received_time	The time at which the contact was received by the dialer	DateTime	Dialer
dial_time	The time at which the contact was sent by the dialer to EFSwitch to be dialed	DateTime	Dialer
campaign_contact_id	The id of the contact received in CCM message payload	VARCHAR(40)	Campaign Manager
campaign_id	The campaign id received in CCM message	VARCHAR(40)	Campaign Manager
start_time	The contact cannot be dialed before this time	DateTime	Campaign Manager
end_time	The contact cannot be dialed after this time	DateTime	Campaign Manager
priority	The contact between 1-10	Integer	Campaign Manager

IVR campaign

Can be provided in an IVR campaign. If not provided, the default value configured in the dialer is used.

Field	Description	Type	Provided By
ivr	The ivr to be selected, THE IVR number, if contact is IVR based	VARCHAR(20)	Campaign Manager

Agent campaign

Mandatory for agent campaigns.

Field	Description	Type	Provided By
dialing_mode	~~PREDICTIVE, PREVIEW or PROGRESSIVE~~ (Not supported)	VARCHAR(20)	Campaign Manager
routing_mode	AGENT or QUEUE, only for contacts with campaign_type = AGENT	VARCHAR(20)	Campaign Manager
resource_id	Queue or AgentId based on routing_mode	VARCHAR(40)	Campaign Manager
queue_name	The name of queue if routing_mode = QUEUE, optional if routing_mode = AGENT or if routing_mode = QUEUE and resource_id is set	VARCHAR(20)	Campaign Manager

Additional Functions

Campaign controls (Voice)

The dialer exposes three APIs that can be called by the campaign manager to start, stop or purge campaigns:

Set this campaign's stopped contacts' status to 'pending'.
Set this campaign's pending contacts' status to 'stopped'.
Remove all pending contacts with this campaign ID.

Check Dialer Status

This API can be used to check the configured value of MAX_CONCURRENT_CALLS and the current number of active calls i.e. contacts with the dialed or agent_pending state.

Failover Cases

Scenarios	Behavior
The voice connector is down and the agent reservation request cannot be sent to it.	Contact status remains on pending and will be tried again.
The database is down and dialer cannot retrieve contacts.	Dialer will retry on its next cycle.
EFSwitch gateway is invalid.	Contact status is set to failed and call result set as Invalid Gateway.
EFSwitch gateway is down.	Contact status set to pending.
EFSwitch is down and call command cant be sent.	Contact status is set to failed.
Campaign manager sends campaign control command(start/stop/purge) to dialer, but database is down.	A Service Unavailable error is returned.
Campaign manager sends campaign control command to dialer, but no entries with supplied campaign ID are found.	A Not Found error is returned.
Voice connector sends agent details to dialer but database is down.	A Service Unavailable error is returned.
Voice connector sends agent details to dialer but an unexpected error occurs e.g. EFSwitch is down.	An Internal Server error is returned.