Teneo Developers

IVR Helper for CSG-IM

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

csg logo

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 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.

For more details on managing files in your solution, see Resource File Manager.

Extension methods


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


1CSGIVRHelper.standardResponse(String outputText, String context, String mode, Map inputConfig)
outputTextMandatory. String containing the text to be spoken.
recognitionContextOptional. Can be used to limit the scope of the speech recognizer for the next input, which can increase its accuracy and responsiveness. These contexts must be arranged with CSG prior to use.
modeOptional. Specifies the type of input to gather for the next input. Possible values: speech, dtmf, both. Defaults to "speech".
inputConfigOptional. Extra configuration options.

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


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


1CSGIVRHelper.transferCall(String outputText, String whisperText, String destinationNumber, boolean bridge, String transfermode)
outputTextMandatory. String containing the text to be spoken.
destinationNumberMandatory. Phone number where the call should be transfered to. Should be a telephone number in the standardized E.164 format. Note that only NANP destinations are currently supported.
whisperTextOptional. String containing the text that should be played to the agent receiving the transfered call.
bridgeOptional. Determines whether the CGI-IM platform remains connected to the call. Defaults to 'false'.
transfermodeOptional. Determines when to connect the user to the transferee. Possible values: dial, answer, accept. Defaults to "accept".

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


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


1CSGIVRHelper.endCall(String outputText, String reason)
outputTextMandatory. String containing the text to be spoken.
reasonOptional. A text describing the reason the call was ended. Defaults to "Teneo ended conversation".

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


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:


1// Optionally specify TTS voice (default: Matthew)
2CSGIVRHelper.MAIN_VOICE = "Joanna"
5// Determine appropriate voice response JSON
6def voiceResponse = ""
7if (_.getOutputParameter("handover")) {
8  def destination = "+1234567890"
9  def whisperText = "This is the whisper message."
10  def bridge = false
11  voiceResponse = CSGIVRHelper.transferCall(_.getOutputText(), destination, whisperText, bridge)
12} else if (_.getOutputParameter("endConversation")) {
13  voiceResponse = CSGIVRHelper.endCall(_.getOutputText())
14} else {
15  def recognitionContext = _.getOutputParameter("recognitionContext")
16  voiceResponse = CSGIVRHelper.standardResponse(_.getOutputText(), recognitionContext)
19// add output parameter to response
20_.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.