IVR Helper for CSG-IM

The CSG IVR extension helps you to seamlessly integrate your Teneo chatbot with the CSG Interactive Messaging platform provided by CSG.

When making your bot available on the CSG Interactive Messaging platform, your users can interact with your bot over a phone line using voice. The platform provides various features, like handover to a live agent and custom recognition contexts to improve the accuracy and responsiveness.

How it works

Once CSG-IM has configured a phone number that points to your published Teneo bot, you can prepare you solution by doing the following:

• Add the CSG IVR extension to your solution
• Add a post processing script to generate the VoiceResponse JSON
• Add parameters to output nodes to end a call, perform a handover or when specific inputs should to be recognized, like phone numbers.

This page explains how to add the extension, describes its methods, provides an example post processing script and explains how to prepare flows to hang up or handover to an agent.

Adding the extension

Add the file CSGIVRHelper.groovy to the Resources in your solution and set the path to /script_lib. This will make the class CSGIVRHelper available that you can use in any script in your solution. The .groovy file is essentially a text file, which can be opened in a text editor. This makes it easy to modify or extend it's source code, without needing to compile it as a class file.

Extension methods

standardResponse

The standardResponse method is used to generate the JSON for standard responses.

CSGIVRHelper.standardResponse(String outputText, String context, String mode, Map inputConfig)

For more details, see the Say and Collect verbs in the CSG-IM API.

transferCall

The transferCall method is used for transferring calls, for example, to hand over a real agent.

CSGIVRHelper.transferCall(String outputText, String whisperText, String destinationNumber, boolean bridge, String transfermode)

For more details, see the Transfer section in the CSG-IM API.

endCall

The endCall method is used to end calls. The IVR platform will send an endsession request to Teneo to end the session.

CSGIVRHelper.endCall(String outputText, String reason)

For more details, see the Disconnect verb in the CSG-IM API.

Usage

The CSG-IVR platform expects the Teneo engine response to contain an output parameter VoiceResponse with the appropriate voice response JSON. The easiest way to add such an output parameter is by using a global post-processing script that automatically adds the output parameter to each response.

Example post-processing script

A post-processing script that uses the CSGIVRHelper class to populate the VoiceResponse parameter can look like this:

// Optionally specify TTS voice (default: Matthew)
CSGIVRHelper.MAIN_VOICE = "Joanna"
CSGIVRHelper.WHISPER_VOICE = "Joanna"

// Determine appropriate voice response JSON
def voiceResponse = ""
if (_.getOutputParameter("handover")) {
  def destination = "+1234567890"
  def whisperText = "This is the whisper message."
  def bridge = false
  voiceResponse = CSGIVRHelper.transferCall(_.getOutputText(), destination, whisperText, bridge)
} else if (_.getOutputParameter("endConversation")) {
  voiceResponse = CSGIVRHelper.endCall(_.getOutputText())
} else {
  def recognitionContext = _.getOutputParameter("recognitionContext")
  voiceResponse = CSGIVRHelper.standardResponse(_.getOutputText(), recognitionContext)
}

// add output parameter to response
_.putOutputParameter("VoiceResponse", voiceResponse)

Script details

Overriding the default TTS voice
The default TTS voice used by the IVR is 'Matthew'. The script above overrides the default voice used by both the standard response as well as the whisper text. The valid TTS names are retrievable from CSG-IM's Platform Service.

Output parameters to specify which methods should be called
The script looks for output parameters that have been added to an output, to determine which details need to be included in the VoiceResponse JSON. Making use of output parameters to tell Teneo which JSON to include is a very convenient way for conversational designers to specify what needs to happen when a particular output node is reached. These are the output parameters the script looks for:

• handover: if this output parameter exists in the current response, the transferCall method is called. Depending on the requirements, the variables destination and whisperText can be dynamically populated based on the context of the conversation.
• endConversation: if this output parameter exists in the current response, the endCall method is called.
• recognitionContext: if this output parameter exists in the current response, the standardResponse will be called and the recognitionContext argument will be provided.
• If none of the above output parameters exist, the standardResponse method will generate the JSON for to say the output and wait for a response.

Adding the final VoiceResponse output parameter
The last line of the script adds an output parameter VoiceResponse to the engine response. This output parameter contains the final JSON that is used by the CSG-IM platform to process the response.

Telling your bot to hang up, handover or provide recognitionContext

The approach above assumes you will add output parameters to outputs where you would like to end a call, transfer to an agent or provide recognition context. A few tips for solutions that are based on the Teneo Dialogue Resources template solution:

• You can add an output parameter endConversation with value true to the flow The user says Goodbye in the Dialogue > Connecting Phrases > Greetings folder.
• Similarly you might want have a look at the The user wants to speak to a real person (Live Chat) flow in Dialogue > My Company, to optimize optimize its answer text and an output parameter handover with value true.
• Since recognition contexts must be arranged with CSG prior to use, where to add the recognitionContext output parameter is determined on a case by case basis. The value for the parameter should be the name of the recognition context provided by CSG.