How to set up IVR scripts to act as CE IVR channels

Contact Expert provides the ability to automate processing certain voice calls by employing IVRs as agents – either Geomant's OnCall IVR product or an Avaya IVR solution. Such a use case is obviously only feasible for fairly simple, self-service type of uniform business processes, however there it can extremely boost overall contact centre efficiency.

CE provides all the necessary resources and configuration options to set this up (e.g. IVR and IVR Channel resources, among others) however there is one particular functionality that needs to be performed on the IVR side, be it a Geomant or Avaya IVR. The IVR script needs to send a signal to CE at the beginning and end of every such voice call via a SOAP webservice ("WS") API. This is on top of the standard call management duties, such as answering and disconnecting the call. Failing to perform this WS based signaling will result in errors such as the IVR CHannels eventually ending up being stuck in an unavailable state (wrapup for example) because CE was not notified that the IVR scripts were done finishing their work.

This article describes the two WS methods that must be used as the minimum: NewCall() and Gone() and the parameters that must be provided to them.

Prerequisites and defaults

On top of the proper configuration of both all of the Voice infrastructure resources and at least one IVR and all associated IVR Channel resources in CE, the basic network access details of the relevant webservice has to be figured out:

Log on to the CE Core Host (application server) as an administrator, navigate to the following path (assuming default install path) and open this file in a text editor: C:\Geomant\CE\Services\ServerAgent\ServerAgent.Config.xml
Find the <Server\> entry with the IVRConnector name and make a note of the value of these parameters:

wsbindingaddress

wsbindingport

The webservice is managed by the IVRConnector service in Contact Expert. The following configuration file controls how many parallel WS transactions it can handle at any one time:

C:\Geomant\CE\Servers\IVRConnectorServer\IVRConnector.ini

The IVRConnector WSDL

The following WSDL describes the API of the IVRConnector WS:

C:\Geomant\CE\Servers\IVRConnectorServer\IVRConnectorServer.WSDL

NewCall()

This method must be called by the IVR script at the beginning of every call, and the following parameters are mandatory:

ivrID – the FQDN or IP address of the relevant IVR resource in Contact Expert. Make sure this is exactly the same as the "FQDN" field content on CE Portal.
channelD – the Channel ID value of the IVR Channel resource in use. Make sure to use the "Channel ID" field content on the CE Portal. Don't use the "Name" field, or the "Extension" field!

A successful call returns the sduID – the unique session identifier of the active call – from CE.

Gone()

This method must be called by the IVR script at the end of every call, and the following parameters are mandatory:

sduID – the unique session identifier of the active call in CE, returned by a successful NewCall() method call.
reason – a numeric reason code that qualifies the call as something like a callback, normal closure, disconnection, or error. (Standard CE reason codes.)

Available Reason Codes for Gone()

The IVR script must pass an integer value in the Gone() call to let CE know what other actions – if any – are needed on the associated contact session. The following reason codes can be used for this purpose.

0 – CLOSE

This should be used every time the IVR script concluded that everything went normally, no errors occurred. CE assigns the major reason code of 48 –*OK_CLOSE for this session.

1 – DISCONNECT

This should be used by the IVR script when the call unexpectedly disconnected in the middle of the flow, but no other technical failures were experienced. CE assigns 49 – OK_DISCONNECT to this session.

2 - CALLBACK

This should only be used by the IVR script when the particular call needs to be rescheduled, the customer requested a callback.

When OK_CALLBACK reason is used, Contact Expert requires additional SDU fields to be set up properly too!

SDU field	Mandatory?	Format	Description
CallbackStartTime	Mandatory!	`YYYY-mm-dd HH:MM:SS`	CE will attempt to launch the callback task starting from this particular point in time.
CallbackEndTime	Mandatory!	`YYYY-mm-dd HH:MM:SS`	CE will attempt to launch the callback task before this particular point in time. Start and end times are allowed to be exactly the same, but the end time must not be sooner than the start time!
Destination	Optional	dialable value	When passed, this must be a value CE is able to dial in the given telephony system. When not passed, CE will reschedule the call with the original called number.

When the above extra SDU fields are not set (or set in an incorrect format), CE will NOT reschedule the task, it will instead close it with an Error reason code!

3 - ERROR

This code means an unexpected, unspecified error happened during the call.