IVR- Installation configuration

From Complete Cyclos documentation wiki
Jump to: navigation, search

Quick installation

This section explains how to:

  • Install all necessary components of the IVR module
  • Configure the basic (minimal) parameters to get Cyclos + IVR running
  • Test the installation

Install components

  • Install Elastix (download the last Elastic ISO file from source forge. Follow the installation guide carefully. (Make sure you write down the keys used during the installation. You will need to later during the installation process).
  • Install Java SDK
  • Install a Tomcat web application server.
  • Install IVR controller at tomcat (by copying the ivr.war file to the tomcat webapps directory)
  • Install Cyclos as explained at the Cyclos wiki
  • Install a 'softphone' that supports the SIP protocol. For example Jitsi (free versions for Linux and Windows)

Configure IVR module

The IVR configuration is done in just two files. In order to get the IVR module running with basic configuration you only need to define a user/password in the ivr.properties file which can be found at the location: /IVR/WEB-INF/classes/

cyclos.url=http://ip_address:8080/cyclos         IP of Cyclos
cyclos.mobilePhoneCustomField=mobilePhone        Mobile phone profile field used for Cyclos
cyclos.msgParamPrincipalType=mobilePhone         Channel used in Cyclos
cyclos.phoneNumberDigits=9                       Number of phone digits
asterisk.server=IP_address                       IP address of Asterisk                    
asterisk.amp.loginUser=cyclosIVR                 User that will connect to the IVR module
asterisk.amp.loginPass=1vrPa55                   Password of User that will connect to the IVR module
agi.server=agi://IP_address                      IP address of the IVR module

Note: The default installation will come pre configured with most of the above parameters

Configure Asterisk/Elastix


Open the file in a text editor.

[cyclosIVR]                 Must be the user name (without []) defined in the IVR controller
secret = 1vrPa55            Must be the password defined in the IVR controller
deny=        Optional blacklist
permit=            IP address of the IVR controller
read = all
write = all

Note: The default installation will come pre configured with most of the above parameters


Open the file in a text editor.

exten => 4321,1,Agi(agi://IP_address/demo.agi)            Change the parameter IP_address by the IP address of the IVR controller 
                                                          (The number '4321' is the number that needs to be dailed at the phone)
Elastix GUI (Web interface)
  • Open de Elastix GUI in a webbrowser
  • Browse to PBX->Extensions->AddExtension
  • Select Device: 'Generic SIP device' and click Submit
  • Many option appear. You only need to fill in the following three parameters:
    • User extension: 123456789
    • Display name: 123456789
    • Secret: abcd1234
  • Click the Submit button, a new page will open with a message at the top 'Apply Configuration Changes'. Click the link to apply the changes.


  • The user extension and name '123456789' is the number of the (soft)phone you will be dialing from. It must be defined in the Mobile phone field of the user in Cyclos that will connect. If you want to test with more users you can create a new extension for each (Cyclos) user.
  • In a real life situation it is not necessary to create an extension for each user. Asterisk will connect to a TELCO Trunk and will capture the callerID automatically.
  • The parameter 'secret' is the (Asterisk) password of the softphone user you will connect with.

Configure Cyclos

  • Through a web browser on a computer on the same subnet as the Elastix server. Type http://<IP>:8080/cyclos (where 'IP' is the IP address Cyclos is running on, and also was defined at the Elastix installation)
  • Enter with the default administration account (user: admin, password: 1234)
  • Create two new members at: Menu - User & Groups > Manage members > Create member: select the group full member.
  • Access the profile of each member and put a valid phone number for both members (field 'Mobile phone)
  • Also via the profile pages (actions for member register a PIN in the External access page.

Test the IVR module

In order to test the IVR module it is more convenient to use a 'softphone' because it does not need any hardware and neither configuring a TELCO connection. We tested with the softphone software Jitsi. But you can use any other softphone or hardware IP phone that supports the SIP protocol. Here are the steps:

Test steps
  • Launch Jitsi
  • The first time it will open a wizzard. If not you can go to 'File - add new account'
  • In the user field you have to put an extension number you created in Asterisk (see above) followed by @ and the IP of Asterisk. (e.g 123456789@
  • In the password field you will have to put in the password you defined in Asterisk (in the example: abcd1234)
  • Now you have to dial the number defined in Asterisk (defined in extensions_custom.conf file: '4321')
  • Follow up the audio menu instructions
Configuration options

There are many ways the IVR module can be configured. Here some examples:

  • In stead of a PIN the login password can be used for authentication (but must be numeric in that case). It is also possible not to require a PIN at all. In that case you will have to rely on the authentication by origin phone number (caller ID).
  • If you want to support more languages you can add a first menu that asks to chose a language (e.g. press 1 for English, or 2 for Spanish)
  • If you call to an extension for which no Cyclos user exist the IVR module will ask you to input your phone number. (This is optional).

Adding new voices

The festival installation in Elastix only comes with English voices. In case you want other voices you can opt for commercial voices or free voice packages for non-commercial use such as Mbrola

Install voice

Note: Spanish voices can be downloaded from http://www.neomano.com/downloads/voces/

Configuration files


This file, that can be found in the directory /IVR/WEB-INF/classes/, contains parameters about the language, the (audio) menu, and operations. This section will explain the common used parameters.

IVR controller parameters
  • language - This parameter defines one or more languages. For each country (and optional variant) a language (voice) file needs to be specified.
  • country - This is an optional parameter that can be used of there are countries with languages. For example US English and Australian English. For more information see the Internationalization section.
  • variant - This is an optional parameter that can be used of there are languages variants within a country. For more information see the Internationalization section
  • messageSource - This parameter is needed for IVR to access the internationalization files. The value needs to be ref=”messageSource”
  • vocalizeParameters - This are additional parameters that can be appended to the text to speech execution (if case used). It permits to control some audio aspects such as voice type, velocity, tone etc.

This example will use the default (English) language without any customization.

<bean id="enIvrUtils" class="nl.strohalm.cyclos.ivr.utils.IvrUtils" init-method="init">
<property name="language" value="en"/>
<property name="messageSource" ref="messageSource"/>
<property name="vocalizeParameters" value=""/>
Menu parameters

In the menu action section you can define up to 10 menu options. In the default configuration of the IVR the first menu level has a language option (English or Spanish). Obviously, this would only be needed in case you want to provide more than one language with a single installation. Here below the possible menu action parameters:

  • timeout - The maximum time out (in seconds) the IVR will wait for input (after the audio message has been played). The default is 0 what means there is no time out. Be aware that every level (option) has it's own timeou parameter
  • defaultOption - This is the default option (when user does not press any menu option). It will point to an existing option. The default value is -1, meaning no default option exists.
  • optionAttempts - The maximum number of times a user can type an invalid option (After which the user will disconnected). The default value is 3.
  • actionOptions - This parameter is a list of possible actions (of type nl.strohalm.cyclos.ivr.IvrAction) and a menu (key) option related to each action.
  • followAutoOption - This parameter would only be set as 'true' for the start menu. When it is 'true' it means that when the start menu is called with autoOption parameter the menu option won't be called but the operation will jump directly to that option. The default value is false. TODO, please give example
  • loopMenuAttempts - The maximum number of times the menu can be reproduced. Si esta opción posee un valor mayor a 0 implica que luego de seleccionada y ejecutada una opción válida se volverá a reproducir este menú (por loopMenuAtteps veces). El valor por defecto de esta propiedad es 0.
Menu translation keys
Key Description Example
title played when entering the menu Welcome to the IVR test system
options Will play a list with the possible menu options Welcome
invalidOption Will play a list with the possible menu options Welcome


When a call is answered by Aterisk it will contact immediately the IVR controller which will wait 300 ms in order for the possible analogical lines to establish a connection. After this it will pass the call on the the base Action class. There are four types of actions:

  • MenuAction: Defines the audio menu (up to 10 options)
  • TransferAction: This action can tranfer incoming calls to other extensions (e.g. call center software)
  • AccountBalanceAction: The action that will handle the Account balance information operation
  • PaymentAction: The action that will handle the Payment operation

The configuration paramters of the Actions are described here below.

General parameters
Menu action
Transfer action
Account balance action
Payment action