Skip to main content
Skip table of contents

EFSwitch Dialer

Work In Progress

This document is a work in progress until details have been finalized.

Requirements

To automate outbound communication with customers via interactive voice response (IVR) systems or agents.

Scenario

  • The campaign information is specified in the user's campaign manager of choice(Mautic etc).

  • This campaign when started is sent to the scheduler which stores the contacts and sends them to CCM at their designated start times.

  • CCM feeds contacts one by one to the voice connector which forwards them to the dialer for storage in a database.

  • The dialer periodically runs a query to retrieve pending contacts from the database:

    • The total number of contacts to be retrieved depends on the current free call slots.

    • These contacts are distributed equally among all campaigns.

  • Appropriate action is taken for each contact based on whether its campaign time is AGENT or IVR.

  • In case of AGENT campaign call, a payload containing call information is sent to the voice connector which requests an agent from the CCM.

    • If an agent is received by the voice connector, the information is sent to the dialer and a call is made to the customer via EfSwitch ESL and bridged to the agent.

    • If an agent is not received then the dialer is notified and it sets the contact back to pending again.

  • One of the following flows will take place based on the dialing mode for agent-based calls:

  • In case of IVR campaign call, a call is made to the customer and an IVR menu plays.

  • In either case, when the call ends:

    • The call result is stored in a database.

    • The call result is sent to the voice connector which sends it to the CCM.

  • In case of agent-call ending:

Flow

Proposed Solution

Contact Structure

The parameters for a campaign contact are set in the campaign manager e.g. Mautic and 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 from CCM

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

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

Dialing Flow

  1. The dialer will periodically query the database and take note of all the campaigns and the number of their contacts present.

  2. It will also take note of the current free call slots.

  3. Based on this information, it will calculate the number of contacts to be retrieved for each campaign such that they are all treated equally.

  4. A set of queries is then run to retrieve the allotted number of 'pending' contacts for each campaign.

  5. These contacts are then sequentially processed based on the campaign type.

IVR Campaigns

  1. For IVR based campaigns, the IVR number is taken from the contact entry if set.

  2. If the IVR number is not provided in the contact entry then the default IVR specified in the dialer configuration is used.

  3. The dialer checks via EfSwitch ESL if the gateway provided is valid.

    1. If it is valid, then the following command is sent to EfSwitch to initiate the call: 

      Originate IVR Call

      JS
      originate {session_in_hangup_hook=true, origination_uuid=call_uuid}sofia/gateway/gateway-id/customerNum IvrNumber XML EfSwitch-IP


    2. If invalid, the contact status is set to 'failed' and it will not be redialed.

    3. If the gateway is down then the contact status is set back to 'pending' to be tried again later.

  4. Once the call ends, the dialer receives a call-ended event from the EfSwitch ESL and:

    1. Stores the call result in the database and sets the status to 'ended'.

    2. Sends the call result to the Voice Connector for a Delivery notification to be sent to the CCM.

Agent Campaigns

  1. If the campaign call type is of 'AGENT', then the contact status is set to 'agent_pending' and call information is posted to the voice connector API.

  2. The voice connector sends back the following payload when it received either an agent reserved or no agent available notification from the CCM:

  3. If no agent was available, the dialer sets the contact status to 'pending' to try again the next time it queries for pending contacts.

  4. If agent was reserved, then the dialer checks via EfSwitch ESL if the gateway provided is valid.

    1. If invalid, the contact status is set to 'failed' and it will not be redialed.

    2. If the gateway is down then the contact status is set back to 'pending' to be tried again later.

    3. In either case call information is sent to the voice connector which will send an END_CHAT payload to the CCM to close the conversation and free up the agent.

  5. The following command is sent to EfSwitch which will call the customer and bridge the answered call to the agent:

    Originate Agent-based Call

    JS
    originate {ignore_early_media=true,session_in_hangup_hook=true,sip_h_X-Destination-Number=<CX-VOICE-SERVICE-ID>,sip_h_X-CallType=<DIALING-MODE>,customer_number=1234,sip_h_X-CALL-VARIABLE0=<CALL-ID>,sip_h_X-Call-Id=<CALL-ID>,domain_name=<EFSWITCH-IP>,record_session=true,call_direction=outbound,sip_h_X-queueType=NAME,sip_h_X-queue='<QUEUE-NAME>',origination_uuid=<CALL-ID>,origination_caller_id_name=<AGENT-EXTENSION>,sip_h_X-agentExtension=<AGENT-EXTENSION>}sofia/gateway/<GATEWAY-ID>/<CUSTOMER-NUMBER> <AGENT-EXTENSION> XML <EFSWITCH-IP>;


  6. Once the call ends, the dialer receives a call-ended event from the EfSwitch ESL and:

    1. Stores the call result in the database and sets the status to 'ended'.

    2. Sends the call result to the Voice Connector for a Delivery notification to be sent to the CCM.

    3. Send call information to the Voice Connector for a call recording link to be sent to CX.

    4. If the customer had declined the call:

      1. The dialer detects the case via the call variables in the call-ended event.

      2. Call information is sent to the voice connector which will send an END_CHAT payload to the CCM to close the conversation.

Additional Functions

Campaign controls

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

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.