IVR- Architecture

From Complete Cyclos documentation wiki
Jump to: navigation, search

Components overview

Main components of the IVR module


PBX (Elastix)

Elastix is an open source Communications Server software that includes IP PBX, email, IM, faxing and collaboration functionality. Elastix has a Web interface and includes capabilities such as a Call Center software with predictive dialing. The Elastix functionality is based on open source projects including Asterisk, HylaFAX, Openfire and Postfix. Those packages offer the PBX, fax, instant messaging and email functions, respectively.
For more information see: http://www.elastix.org/


Asterisk is open source PBX server software that can attend VoIP (Voice over IP) calls. Asterisk also supports calls via traditional analogical lines (T1 and E1). In that case a hardware adapter is need in order to transfer the analogue data from copper lines to VoIP traffic. Asterisk can connect to phone operator networks via gateways or directly to the operator services.
Information about asterisk can be found: http://www.asterisk.org

The configuration of external and internal extensions can be configured manually in Asterisk or using a graphical tool such as FreePBX (http://www.freepbx.org/)
TODO: At least an internal connection that will transfer the incoming calls to a Fast AGI is needed. And a secondary internal connection with a connected Software Phone or an external line. desde qui se llamara al interno configurado con el módulo IVR ??

Festival (Text To Speech)

Festival is software that allows 'text to speach' (TTS) functionality. With this it is possible to define the audio of the PBX module (e.g. 'please type your PIN number'). Another option is to record audio files for each message.
More information about festival can be found here: http://festvox.org/festival/.

IVR module

The IVR module runs as a separate Java Web application. It has an interface for the communication with the PBX (Asterisk) and to Cyclos. When a call is attended by Asterisk the control of the call is passed on to the IVR controller. The controller will determine the correct vocalizations (audio arquives) to be reproduced, it will capture data input (keypad typing), handle business rules (via Cyclos communication), and optionally generate outgoing calls.

Asterisk-Java Lib

The Asterisk-Java package consists of a set of Java classes that allow you to easily build Java applications that interact with an Asterisk PBX Server.
For examples of the use of Asterisk Java see: http://asterisk-java.org/development/tutorial.html

Fast Asterisk Gateway Interface (Fast AGI)

The Asterisk Gateway Interface provides the technology for Asterisk to relay (delegate) the call handling to remote software (the IVR module) over a network connection.
Documentation about the AGI can be found here:

Asterisk AGI interface: http://www.voip-info.org/wiki/view/Asterisk+AGI
Asterisk dial plan configuration: http://www.voip-info.org/wiki/view/Asterisk+config+extensions.conf http://www.voip-info.org/wiki/view/Asterisk+howto+dial+plan
Asterisk Fast AGI: http://www.voip-info.org/wiki/view/Asterisk+FastAGI

Asterisk manager

The Asterisk Manager Interface (AMI) allows a client program to connect to an Asterisk instance and issue commands or read events over a TCP/IP stream. Integrators will find this particularly useful when trying to track the state of a telephony client inside Asterisk, and directing that client based on custom (and possibly dynamic) rule.
For more information: http://www.voip-info.org/wiki/view/Asterisk+manager+API

Cyclos Web service API client

This client is the element of the IVR module that will connect to the Cyclos Web services (explained below in the configuration section). An example of a web service client can be found here. http://www.cyclos.org/wiki/index.php?title=Web_services#Writing_client_applications

The Web Services are using the CXF framework. The IVR module will use those web services to handle the operations.
Information about the Cyclos Web Services API can be found here: http://project.cyclos.org/wiki/index.php?title=Web_services

The SMS module is using the same Web Services API and can be used as a reference for the IVR operations.
Information about the SMS module can be found here: http://www.cyclos.org/wiki/index.php/Introduction


Cyclos will communicate with the IVR channel over Web services. This is straightforward. First a new ‘access channel’ needs to be created in Cyclos. Additionally the Web Services needs to be configured to define the access needed by the IVR module. The document “Cyclos configuration for external channels (SMS / USSD / IVR) “ describes these steps in detail. Obviously, Cyclos will need some users with accounts and a balance in order to be able to make payments. How to configure this is also explained in the above mentioned document.

Technical structure IVR module

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

Detailed information about the Actions and their possible parameters are explained at the page Parametrization