IVR Blocks
- Valerio Ciotta
- Product Knowledge
- XCALLY Knowledge (Unlicensed)
Cally Square IVR Blocks
This section explains which are the blocks available in Cally Square.
To design your IVR flow drag and drop blocks (ready-to-use applications) in the design area and connect them in a flow:
|
For each block you add, just double click on it and enter the required fields in the pop up screen to setup the corresponding application:
|
On this Page:
The blocks are collected in Groups of Applications: in the following sections you can find all available application for each group.
Entry group applications
This group - start, finally and end - manages the begin and the end of a call from an Application point of view.
Start | Description The Start block must be the very first one in each IVR application. The application will not be published without the Start box: it can be used just once for each IVR. Parameters
Exit Arrows This block provides just one arrow out to the next step |
Finally
| Description This block is executed when the application loses the voice channel. It should be used for example to write some data on a DB after the call hangup or at the end of each IVR. You can use all the boxes you want after the finally. Of course boxes for audio playing will not have any effect on the customer experience. Parameters
Exit Arrows This block provides just one arrow out to the next step |
End
| Description This box needs to be placed at the end of every leaf of the IVR tree. You can put an End box either at the end of each leaf or have a unique End box whom all the leaves connect to. Parameters
Exit Arrows This box does not have exit arrow |
Call management applications
This group of boxes - answer, hangup, internal dial, external dial, queue, voicemail, callback - can be used to manage the begin and the end of a call from a Telephony point of view.
Answer
| Description This box picks up the call and opens also the voice channel Parameters
Exit Arrows This box provides just one arrow out to the next step |
Hangup | Description This box hangs up the call to the customer on the remote party Parameters Label: here you can type a brief description of the box Exit Arrows This box has got any exit arrow |
Internal Dial
| Description This box performs the standard Asterisk Dial command towards an internal phone Parameters
Exit Arrows This box provides just one arrow out to the next step |
External Dial | Description This box performs the standard Asterisk Dial command towards an external phone Parameters
|
Queue | Description This box performs the standard Asterisk Queue command in order to manage calls to a Queue (especially useful for ACD or asterisk call center applications). Parameters
Exit Arrows This box provides just one arrow out to the next step |
Voicemail | Description This box performs the standard Asterisk Voicemail command** in order to route your call flow to a pre-defined Asterisk voicemail box and context. Parameters
Exit Arrows This box provides just one arrow out to the next step |
Callback | Description The callback block will add the contact in the selected contact manager list. Please remember to associate the list to a queue campaign for Motion Bull to call the contact at the scheduled time. Parameters
Exit Arrows This box has got one exit arrow |
Agent management applications
This group of blocks allow to manage the Agents' status:
- add agent to all the queues he belongs to (Login)
- remove agents to all the queues he belongs to (Logout)
- pause agents on all the queues he belongs to (Pause)
- end pause agent on all the queues he belongs to (End Pause)
This group of blocks can be used in an IVR in order to manage the queue status of the Agents who use external phones (soft phones, hard phones or mobile phones) instead of (or blended with) the traditional Phonebar or the WebRTC bar Agents.
Login
| Description This box allows to add an agent to all the queues he belongs to. Parameters In order to find the Agent's queues, you need to set the column where the script must search the caller number.
Exit Arrows For this box you must create two exit arrows using the following values:
|
Pause | Description This box allows to pause an agent on all the queues he belongs to. Parameters In order to find the Agent's queues, you need to set the column where the script must search the caller number.
Exit Arrows For this box you must create two exit arrows using the following values:
|
End Pause | Description This box allows to end the pause of an agent to all the queues he belongs to. Parameters In order to find the Agent's queues, you need to set the column where the script must search the caller number.
Exit Arrows For this box you must create two exit arrows using the following values:
|
Logout | Description This box allows to log out an agent to all the queues he belongs to. Parameters In order to find the Agent's queues, you need to set the column where the script must search the caller number.
Exit Arrows For this box you must create two exit arrows using the following values:
|
Variable nodes and math
This group of boxes handles the variables and math operations.
Set
| Description The box lets you set the value of a variable (previously defined in the IVR dashboard) Parameters
please note the variable format is slightly different from the Asterisk one. DO NOT use the $ character before the {}. Example: the usual asterisk variable ${CALLERID(num)} MUST be defined just as {CALLERID(num)} in the Cally Square environment. Exit Arrows The box provides just one arrow out to the next step |
Math | Description Here you can perform complex mathematical operations during the call flow Parameters
i.e. ({RECORD}*2)-4*7/(5*3)+62 i.e. array handler: '{INPUT_DATA}.split(";")'
Exit Arrows The box provides just one arrow out to the next step |
Play and Menu nodes
This group manages the audio playing.
Playback
| Description Here you can play an audio file without any interaction between the customer and the application. The audio is unstoppable Parameters
Exit Arrows This box provides just one arrow out to the next step |
Menu
| Description This is probably one of the most important application box available on Cally Square. Here you can build a complex menu using a single box: you can play the message, count the retries on errors (i.e. to avoid dangerous loops) and set a variable with the digit value(s) pressed by the customers Parameters
** Please consider the menu box gives the top priority to the invalid (i) or timeout (t) branches (if present) before routing the call in a loop.
Exit Arrows The menu box lets you draw many exit arrows according to the following syntax:
It is possible to add multiple choices for each output branch: use just the comma separated characters. |
Say Digits
| Description Here you can play the digits, one by one, in the chosen language (defaults to English) Parameters
Exit Arrows This box provides just one arrow out to the next step |
Say Number | Description Here you can play a number (i.e. 2583 will be played like "two thousand, five hundred and eighty threes") Parameters
Exit Arrows |
SayPhonetics | Description Here you can sequentially play each asterisk sound file located in /var/lib/asterisk/sounds/phonetic/character_p.gsm for each character in input using the NATO Phonetic Alphabet. Parameters
Exit Arrows |
GetDigits | Description Here you can prompt the user to insert a series of digits: you can play the message, count the retries on errors (i.e. to avoid dangerous loops) and set a variable with the inserted digits value. Parameters
** Please consider that the getdigits box gives the top priority to the invalid (i) branch (if present) before routing the call in a loop. Exit Arrows The getdigits box lets you draw many exit arrows according to the following syntax:
|
GetSecretDigits
| Description Here you can prompt the user to insert a series of digits and some of them will be hidden, for security reasons. You can play the message, set how many digits you want to hide, count the retries on errors (i.e. to avoid dangerous loops) and set a variable with the inserted digits value. Parameters
** Please consider that the getsecretdigits box gives the top priority to the invalid (i) branch (if present) before routing the call in a loop. Exit Arrows The getsecretdigits box lets you draw many exit arrows according to the following syntax:
|
Recording
The following section explains how to perform live recordings of calls.
Record
| Description This box performs a .wav call recording to a file of the current Asterisk channel
Built-in variables We provide the following Asterisk channel variables named
which show the filename of the recording in the file system without extension. Exit Arrows This box provides just one arrow out to the next step |
TTS - Text to Speech
In this section you find the blocks which can be used for text to speech conversion.
GoogleCloudTTS
| Description This box lets you perform a Text-To-Speech conversion using the Google Cloud TTS* *Internet connection is required for this box to work Parameters
Exit Arrows This box provides just one arrow out to the next step |
GoogleTTS
| Description This box lets you perform a Text-To-Speech conversion using the Google TTS*. *Internet connection is required for this box to work Parameters
Exit Arrows This box provides just one arrow out to the next step Please note google TTS is offered without any warrant. You need a valid internet connection to make it working. Furthermore it is pure experimental and it can bring to unexpected behaviors. |
ISpeechTTS
| Description This box lets you perform a Text-To-Speech conversion using the Ispeech TTS Agi* Parameters *Internet connection is required for this box to work Parameters
Exit Arrows This box provides just one arrow out to the next step. Please note Ispeech TTS require a valid key from the ispeech.org website and a sufficient amount of acquired credits. The translation use 1 credit for each word. Remember: this software is managed by others. Check if it works properly. |
AWSPolly
| Description This box enables a voice-to-text conversion function using AWS Polly Agi Parameters*. For additional information see https://aws.amazon.com/polly/ Remember: this software is managed by others. Check if it works properly. Parameters
Exit Arrows This box provides just one arrow out to the next step |
LumenvoxTTS
| Description This box lets you perform a Text-To-Speech conversion using the Lumenvox TTS* *In order to make this box work you must install Lumenvox on a machine that is reachable by your system. Parameters
You are not required to supply any options. Multiple options can be provided by joining options with an ampersand, e.g. l=en-US&g=female Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. |
SestekTTS
available from rel. 2.0.84 | Description This box lets you perform a Text-To-Speech conversion using the Sestek TTS. Parameters
You are not required to supply any options. Multiple options can be provided by joining options with an ampersand, e.g. l=en-US&g=female Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. |
MRCPSynth
available from rel. 2.5.2 | Description This box lets you perform a Text-To-Speech conversion using the MRCPsynth TTS* *In order to make this box work you must install MRCPsynth on a machine that is reachable by your system. Parameters
You are not required to supply any options. Multiple options can be provided by joining options with an ampersand, e.g. l=en-US&g=female Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. |
ASR - Automatic speech recognition
In this section you can find the blocks used for voice-to-text functions.
GoogleASR
| Description This box allows you to do a voice-to-text conversion using the Google ASR Agi* Parameters*Internet connection is required for this box to work Parameters
Please note Google ASR require a valid key from the console.developers.google.com website and a sufficient amount of acquired credits. Furthermore it is pure experimental and it can bring to unexpected behaviour.
Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. | ||||||||||||||||||||||||
ISpeechASR
| Description This box allows you to do a voice-to-text conversion using the Ispeech ASR Agi* Parameters*Internet connection is required for this box to work The ASR saves the results in two channel variables:
Parameters
Please note Ispeech ASR require a valid key from the ispeech.org website and a sufficient amount of acquired credits. Furthermore it is pure experimental and it can bring to unexpected behaviour. Each dictation processing requires 1 credit. Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. | ||||||||||||||||||||||||
LumenvoxASR
| Description This box allows you to do a voice-to-text conversion using the Lumenvox ASR application* *In order to have this box working you must install Lumenvox on a machine that is reachable by your system. The ASR save the results in three channel variables:
Parameters
If you need to use the multiple grammar, the value of the first grammar must be separated from the second one using a character defined (e.g.: grammar-a%grammar-b, defining the % as a delimiter in the options field gd):
LumenVox provides the following built-in grammars:
Options: Options control details about the recognition. Valid options are:
You are not required to supply any options. Multiple options can be provided by joining options with an ampersand, e.g. f=sayHelloWorld&t=5000 Exit Arrows This box provides just one arrow out to the next step. Remember: this software is managed by others. Check if it works properly. | ||||||||||||||||||||||||
TildeASR
| Description This box allows you to do a voice-to-text conversion using the Tilde ASR Agi* Parameters *Internet connection is required for this box to work The ASR saves the results in two channel variables:
Please note Tilde ASR require a valid app key from the tilde.com website and a sufficient amount of acquired credits. Furthermore it is pure experimental and it can bring to unexpected behaviour. Parameters
Exit Arrows This box provides just one arrow out to the next step. Remember: this software is managed by others. Check if it works properly. | ||||||||||||||||||||||||
SestekASR
available from rel. 2.0.84 | Description This box allows you to do a voice-to-text conversion using the Sestek ASR* *Internet connection is required for this box to work The ASR save the results in three channel variables:
Parameters
You are not required to supply any options. Multiple options can be provided by joining options with an ampersand, e.g. f=sayHelloWorld&t=5000 Exit Arrows This box provides just one arrow out to the next step. Remember: this software is managed by others. Check if it works properly. | ||||||||||||||||||||||||
MRCPRecog
available from rel. 2.5.2 | Description This box allows you to do a voice-to-text conversion using the MRCPRecog application* *you must install MRCPRecog on a machine that is reachable by your system for this box to work The ASR save the results in three channel variables:
Parameters
If you need to use the multiple grammar, the value of the first grammar must be separated from the second one using a character defined (e.g.: grammar-a%grammar-b, defining the % as a delimiter in the options field gd):
MRCPRecog provides the following built-in grammars:
Options: Options control details about the recognition. Valid options are:
You are not required to supply any options. Multiple options can be provided by joining options with an ampersand, e.g. f=sayHelloWorld&t=5000 Exit Arrows This box provides just one arrow out to the next step. Remember: this software is managed by others. Check if it works properly. |
Integration Server
This group provides the capabilities to connect the IVR application with a remote DB Schema, so to perform queries and operations. 
Database
| Description This box lets you perform a query to a DB schema. You must define a DB connection according to the instructions (please refer to the ODBC section) Parameters
i.e.: the variable name is RESULT and the query is "SELECT order_num FROM orders" the query result will be saved into a matrix as follows: RESULT[0][order_num] RESULT[1][order_num] RESULT[2][order_num] RESULT[3][order_num] RESULT[n][order_num] Built-in variables We provide the following Asterisk channels variables named
Example: RESULT_ROWS_COUNT Exit Arrows This box provides just one arrow out to the next step |
SendMail
| Description This box lets you send an email to a specified email address(es). Before using this block, please configure the email accounts under the Email channel or the SMTP section. Parameters
Exit Arrows This box provides just one arrow out to the next step |
SendSMS
| Description This box lets you send a text message (SMS) to one recipient Parameters
The recipient number must be:
Exit Arrows This box provides just one arrow out to the next step |
Dialogflow
DEPRECATED FROM REL. 2.5.7 | Description This box allows you to build a voice bot using the Google Dialogflow integration (click clip1 and clip2 and learn more about this topic!) *Internet connection is required for this box to work Parameters
Please note Dialogflow require a valid key from the console.dialogflow.com website and a sufficient amount of acquired credits. Furthermore it is pure experimental and it can bring to unexpected behaviour. The Dialogflow block saves the results in the following variables:
Release notes DIALOGFLOW_ENDCONVERSATION and DIALOGFLOW_ISFALLBACKINTENT variables are available from version 2.0.77 Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. click here to learn more about voicebot triggers useful to enable conversation transcript view |
DialogflowV2
available from rel. 2.5.7 | Description This box allows you to build a voice bot using the Google Dialogflow integration *Internet connection is required for this box to work Parameters
Please note Dialogflow requires a valid Service Account Key and a sufficient amount of acquired credits. Furthermore it is pure experimental and it can bring to unexpected behaviour. The DialogflowV2 block saves the results in the following variables:
Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. click here to learn more about voicebot triggers useful to enable conversation transcript view |
Amazon Lex
available from rel. 2.0.77 | Description This box allows you to build a voice bot using the Amazon Lex integration. For additional information see https://docs.aws.amazon.com/en_us/lex/latest/dg/getting-started.html *Internet connection is required for this box to work Parameters
The Amazon Lex block saves the results in the following variables:
Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. click here to learn more about voicebot triggers useful to enable conversation transcript view |
SestekNDA
available from rel. 2.0.84 | Description This box allows you to build a voice bot using the Sestek NDA* Integration. *Internet connection is required for this box to work Parameters
The SestekNDA block saves the results in the following variables:
Exit Arrows This box provides just one arrow out to the next step Remember: this software is managed by others. Check if it works properly. |
RestAPI
available from rel. 2.4.12 | Description This box allows you to use Restful API to GET, POST, PUT, DELETE data from external applications or sources (for example: ticketing systems, CRM, order systems, and so on). The result of the API request (Body) can also be stored in a Variable. *Internet connection is required for this box to work Parameters
Custom script guidelines You can valorize custom variables to use in you request using a nodejs script located on your server. You can insert the absolute path to the script inside the Computed Variables Script Path input. Remember to follow these important rules:
module.exports = function({options_object}, callback){ // custom code var variables = { code output as object }; // it must be an object, not an array callback(null, variables); } The script also receives the options you inserted in the restAPI block, including URL and method, so you can use them in the script if needed. e.g. const { URL } = require('url'); module.exports = function(options, callback){ var request = options; var method = request.method; var uri = request.uri; const myURL = new URL(uri); var host = myURL.host; var hostname = myURL.hostname; var href = myURL.href; var pathname = myURL.pathname; // etc... // additional custom code var variables = { code output as object }; callback(null, variables); } Variables and custom (script) variables To include asterisk variables in your URL, you must include them in curly brackets. e.g. https://myurl.com?phone={CALLERID(num)} The same apply if you want to include them in the body of your request, or in your headers ( pay attention to the quotes ""). e.g. { "phone":"{CALLERID(num)}" } To include custom (script) variables, you must include them in double dollar $$ symbols. e.g. Your script returns an object like this: { key1: "value1", key2: "value2" } To use them in your URL you can write: https://myurl.com?myvar1=$$key1$$&myvar2=$$key2$$ and it will be completed like this: https://myurl.com?myvar1=value1&myvar2=value2 The same apply if you want to include them in the body of your request, or in your headers ( pay attention to the quotes ""). So, if your body/header object is written like this: { "myvar1":"$$key1$$", "myvar2":"$$key2$$" } it will be completed like this: { "myvar1":"value1", "myvar2":"value2" } NOTE: All special chars in the returned strings from the script are escaped ( e.g. the slash / character is translated to ', so if you want to avoid that you need to in clude an & symbol before the variable name: e.g. { "myvar1":"$$&key1$$", "myvar2":"$$&key2$$" } Built-in variables We provide the following Asterisk channels variables named
Exit Arrows This box provides just one arrow out to the next step |
Call Flow
In this group you find the boxes useful to design the call flow according to:
- The interaction between the customer and the application
- The query results
- The arithmetic calculation results
- Other
Goto
| Description This box lets you divert the call to another object like
Parameters
If you use Cally Square combined with XCALLY this should be:
Exit Arrows This box provides just one arrow out to the next step The goto block will interrupt the IVR execution and route the call toward another extension, but before that it will execute any finally block with all its other following blocks, if there is any. |
Gotoif | Description Performs a conditional jump according to a comparison result Parameters
A Condition example: '{CHANNEL(language)}' == 'en' || '{CHANNEL(language)}' == 'fr' The above condition is TRUE when the channel language is English or French JS Operators For more information, please refer to: Exit Arrows For this box you must create two exit arrows using the following values:
|
GotoifTime
| Description This box lets you take decisions based on the time intervals** Parameters
Exit Arrows For this box you must create two exit arrows using the following values:
|
Switch | Description This block is very similar to the menu block, unlike the fact that the pat the call will take depends on a variable. Indeed you can set a variable to be read and choose a branch depending on its value. Parameters
Exit Arrows The block lets you draw many exit arrows depending on how many values the variable can assume. -: In addition there is a branch in case none of the branches values match the value of the variable It is possibile to add multiple choices for each output branch: just use the comma separated characters. |
Stats
Goal
| Description Thanks to this box you can set a goal into the IVR structure and have a trace if the user has reached this goal, on the database. This can be useful for the IVR Statistics, that you can extract in the XCALLY Analytics section. Parameters Label: brief description Goal Name: the name of the goal Exit Arrows This box provides just one arrow out to the next step |
General
NoOp
| Description The box lets you put a label message in your application. You will find the label in the CLI log on the asterisk console (asterisk –r on your Linux machine). The purpose of the NoOp box is to help your application debug Parameters
Exit Arrows This box provides just one arrow out to the next step |
System | Description Calls an external command or script Parameters
Exit Arrows This box provides just one arrow out to the next step |
AGI | Description The Asterisk Gateway Interface is an interface you can use to add functionality to Asterisk using many different programming languages: Perl, PHP, C, Pascal, Bourne Shell etc... This box lets you to perform an AGI command Parameters
Exit Arrows This box provides just one arrow out to the next step |
SubProject
| Description This box calls another Cally Square project inside the current one. It’s useful to mange complex projects, so you can make separate simpler projects and recalling them inside a main one. Parameters
Exit Arrows This box has one exit arrow |
Custom App | Description This box allows to run Asterisk applications (see here for further information) in your IVR flow. Parameters
Exit Arrows This box has only one exit arrow. |
For additional information please refer to the Asterisk Applications Guide
Important
A callback scenario is something in which your customers waiting in queue can optionally be diverted to a callback capability. Such capability invites the customer to leave the queue, thus the call center will call him/her back in a lighter traffic period. This feature is mostly used with a queue campaign and it works only if you have the Motion Dialer license
Let's consider that Queue campaign time interval is from 8:00-18:00 and Callback Delay is 30 min. If a customer calls in at 17:40 and decided to be called back, the contact will be scheduled for 18:10. Keep in mind that this is out of the campaign time interval hence Motion Bull will call the contact in the next valid time interval and when there is at least one available agents.
Agent Management Sample IVR
You can find a sample Agent Management IVR Project on your server: see here how it works.
Important
The mathematical operation must follow the javascript rules: Operators and String Methods.
** Example of Filename: recording-{EPOCH}-{CALLERID(num)}
(You will get something like recording-1393061376-243534507 where 1393061376 is the timestamp and 243534507 is the caller number)
The recordings will be available for listening inside the Recordings section.
About REST API
A RESTful API (REST is an acronym for Representational State Transfer) is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data: the client requests the server for the required information, via an API, and then, the server sends a response to the client.
The data returned by the server, in response to the request of the client is either in the format of JSON or XML. Both JSON and XML format have a proper hierarchical structure of data. REST is an architectural style as well as an approach for communication purposes that is often used in various web services development (the architectural style of REST helps in leveraging the lesser use of bandwidth to make an application more suitable for the internet).