IVR Structure Blocks
- Valerio Ciotta
- XCALLY Knowledge (Unlicensed)
If you drag and drop a box in the design area and double click on it, you will get a pop up appearing:
Inside the pop up you will find the proper fields to be filled in order to setup the box according to your application logic.
Please check the following list for the complete parameter lists.
Please note that you can navigate the design area only through the IVR project preview that you see in the left of the screen:
Entry group applications
This group - start, finally and end - manages the begin and the end of a call from an Application prospective.
STARTDescription The Start box has to be the very first box in every IVR application. The application will not be published withuot the Start box: it can be used just once for each IVR.Parameters Label: here you can type a brief description of the boxExit Arrows This box provides just one arrow out to the next step |
FINALLYDescription This box 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 Label: here you can type a brief description of the boxExit Arrows This box provides just one arrow out to the next step |
ENDDescription 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 having a unique End box to whom all the leaves connect. Parameters Label: here you can type a brief description of the box Exit Arrows This box has not any exit arrow |
Call management
This group of boxes - answer, hangup, internal dial, external dial, queue, voicemail, callback - manages the begin and the end of a call from a Telephony prospective.
ANSWERDescription This box picks up the call and open also the voice channelParameters Label: here you can type a short description of the box Timeout: here you can setup a timeout in seconds the customer will wait before the system picks up the call. During that period the customer will hear to the “Music On Hold” if it is configured on your Asterisk server.Exit Arrows This box provides just one arrow out to the next step |
HANGUPDescription This box hangs up the call to the customer on the remote partyParameters Label: here you can type a brief description of the boxExit Arrows This box has got any exit arrow |
INTERNAL DIALDescription This box performs the standard Asterisk Dial command towards an internal phone Parameters Label: here you can type a brief box description Identifier: the agent that you want to call (i.e. john.doe (998)) Timeout: the maximum dial time in seconds (default is 60 s). Options: here you can type the asterisk dial options parameter (it is optional). URL: this parameter will also be sent to the called party upon successful connection (it is optional). Exit Arrows This box provides just one arrow out to the next step |
EXTERNAL DIALDescription This box performs the standard Asterisk Dial command towards an external phoneParameters Label: here you can type a brief box description Phone: the number that you want to call (i.e. 012345678) Trunk: the trunk that you want to use for the call Timeout: the maximum dial time in seconds (default is 60 s). Options: here you can type the asterisk dial options parameter (it is optional). URL: this parameter will also be sent to the called party upon successful connection (it is optional). |
Queues
The following section allows to perform the Asterisk Queue command in order to manage calls to a Queue (especially useful for ACD or asterisk call center applications).
QUEUEDescription This box performs the standard Asterisk Queue commandParameters Label: here you can type a brief box description Queue name: name of the Asterisk pre-defined queue Options: queue command options. It may contain zero or more of the following characters: d: data-quality (modem) call (minimum delay) h: it allows the callee to hang up by pressing * H: it allows the caller to hang up by pressing * n: no retries on the timeout: it exits this application and goes to the next step r: ringing instead of playing MOH R: stops moh and rings once an agent is ringing (Asterisk Trunk) t: it allows the called user to transfer the calling user T: it allows the calling user to transfer the call. w: it allows the called user to write the conversation to disk via Monitor W: it allows the calling user to write the conversation to disk via Monitor c: continuing in the dialplan if the callee hangs up (Asterisk 1.6.0 and above) i: it ignores the call forward requests from queue members and do nothing when they are requested (Asterisk 1.6.0 and above) k: it allows the called party to enable parking of the call by sending the DTMF sequence defined for call parking in features.conf (Asterisk 1.6.0 and above) K: it allows the calling party to enable parking of the call by sending the DTMF sequence defined for call parking in features.conf (Asterisk 1.6.0 and above). x: it allows the called user to write the conversation to disk via MixMonitor (Asterisk 1.6.0 and above). X: it allows the calling user to write the conversation to disk via MixMonitor (Asterisk 1.6.0 and above). Timeout: time in seconds a call will wait in the queue before it is routed to the next priority in the dialplan (if not defined or 0 the default behaviour is unlimited) URL: external URL (when supported) AGI: AGI script invoked when a queue member answers the call Exit Arrows This box provides just one arrow out to the next step |
Voicemail
The following box provides the voicemail command features, in order to route your call flow to a pre-defined Asterisk voicemail box and context.
VOICEMAILDescription This box performs the standard Asterisk Voicemail command**Parameters Label: here you can type a brief box description Box number: here you can set the voicemail box where you want to route the call (the name that you previously configured into the Voicemail section) Context: the context where you have defined your voicemail box (xCALLY voicemail default context is from-voicemail) Exit Arrows This box provides just one arrow out to the next step |
Callback
CALLBACKImportant: the callback works ONLY if you have installed the additional Tiger Dial module. Description 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. Parameters Label: here you can type a brief description of the box Name: (optional) if you set this field, the value will be shown on the Phone bar Popup. Phone: the phone number of the customer that you want to call back. Default: the CallerID. List Name: the name of the list where the contact will be added. Delay: here you can insert a variable that defines when the customer will be called again (the Customer digits the number - in minutes - for example 15; 15 minutes later the system will automatically call him and connect him with one available Agent - see the example here Callback#PlannedCallBackIVR). Exit Arrows This box has got one exit arrow Built-in variables We provide the following Asterisk channels variable named SHUTTLE[CALLBACK][PHONE] with value as "Phone" field of the Callback block. |
Here you can find some Callback examples
Variable nodes
This group of boxes handles the variables.
SETDescription The box lets you set the value of a variable (previously defined in the IVR dashboard)Parameters Label: here you can type a short description of the box Variable: pickup list you can use to choose the variable you want to use, selecting from the variable list previously defined into the dashboard Value: variable value, like the following ones: o Constant (digits or text) o An Asterisk variable in the format {VARIABLE_ASTERISK} o A generic non-asterisk variable previously defined in the Cally Square dashboard, in the format {VARIABLENAME} o Etc IMPORTANT: 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. |
Example: change the asterisk default language
In order to be able to use the SET box during the call flow for setting or change the default language (used for example for prompts), it’s possible to define a channel variable under the VARIABLE section, called CHANNEL(language). See below screenshot for example.
Math operations
The math box can handle complex elaborations.
MATHDescription Here you can perform complex mathematical operations during the call flowParameters Label: here you can type a short description of the box Operation**: the mathematical operation i.e. sqrt(({RECORD}*2)-4*7/(5*3)+62) i.e. array handler: explode( ',', '{INPUT_DATA}') Result: variable used to store the operation output Exit Arrows The box provides just one arrow out to the next step |
** The operation must follow the php rule you can find listed here:
Functions:
http://www.w3schools.com/Php/php_ref_math.asp
Operators:
http://www.w3schools.com/php/php_operators.asp
Please note in the above example {RECORD} is the name of the Asterisk variable.
Do not use { } for other php functions!
Play and Menu nodes
This group manages the audio playing.
BACKGROUNDDescription This box allows you to set the value of a variable previously defined in the IVR dashboardParameters Label: here you can type e a brief description of the box Filename: then name of the audio file you want to play Response Timeout: the maximum number of seconds the system waits before considering the customer not interacting with the application Max Digit: the maximum number of digits the system waits before moving on to the next step Exit Arrows This box lets you draw many exit arrows according to the following syntax: X: the box waits for one digit if the MaxDigit parameter is set to one XX: the box waits for exactly N digits (in this example N=2) i: the system takes this path if the entry selected is invalid t: the system takes this path if the box goes in case of timeout | |
PLAYBACKDescription Here you can play an audio file without any interaction between the customer and the application. The audio is unstoppableParameters Label: here you can type e a brief description Filename: name of the audio file you want to play in the current boxExit Arrows This box provides just one arrow out to the next step | |
| |
GET DIGITSDescription 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 Label: here you can type e a brief description ** Please consider that the getdigits box gives the top priority to the invalid (i) branch (if present) before routing the call in a loop. Pressing the # key has the same effect as the timer running out: the command ends and any previously keyed digits are returned. A side effect of this is that there is no way to read a # key using this command. If the user doesn't press any keys when the message plays, there is $timeout milliseconds of silence then the command ends. The user has the opportunity to press a key at any time during the message or the post-message silence. If the user presses a key while the message is playing, the message stops playing. When the first key is pressed a timer starts counting for $timeout milliseconds. Every time the user presses another key the timer is reset. The command ends when the counter goes to zero or the maximum number of digits is entered, whichever happens first. Exit Arrows The getdigits box lets you draw many exit arrows according to the following syntx
| |
GET SECRET DIGITSDescription 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 Label: here you can type e a brief description Filename: the name of the audio file you want to play in the current box Response Timeout: the maximum number of seconds the system waits before considering the customer not interacting with the application Min Digit: the minimum number of digits the system can accept without considering it an invalid entry Max Digit: the maximum number of digits the system waits before moving on to the next step Retry: here you can set the number of loops automatically performed in case of invalid digits ** Number Hidden Digits: the number of digits that the system will hide, for security reasons Position Hidden Digits: you can set if the First or Last #N digits will be hidden Variable: the variable you want to fill with the digits pressed by the customer. ** Please consider that the getsecretdigits box gives the top priority to the invalid (i) branch (if present) before routing the call in a loop. Pressing the # key has the same effect as the timer running out: the command ends and any previously keyed digits are returned. A side effect of this is that there is no way to read a # key using this command. If you don't specify $max_digits then the user can enter as many digits as they want. If the user doesn't press any keys when the message plays, there is $timeout milliseconds of silence then the command ends. The user has the opportunity to press a key at any time during the message or the post-message silence. If the user presses a key while the message is playing, the message stops playing. When the first key is pressed a timer starts counting for $timeout milliseconds. Every time the user presses another key the timer is reset. The command ends when the counter goes to zero or the maximum number of digits is entered, whichever happens first. Exit Arrows The getsecretdigits box lets you draw many exit arrows according to the following syntx | |
SAY DIGITS Description Here you can play the digits, one by one, in the chosen language (defaults to English) Parameters - Digits: the digits you want to be played: they can be both a digit string (i.e. 1234) or a VARIABLE (i.e. {CALLERID(num)}) - Escape digits: special character to exit from the playing (i.e. #) 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 - Number: the number you want to be played: they can be both a digit string (i.e. 1234) or a VARIABLE (i.e. {CALLERID(num)}) - Escape digits: special character to exit from the playing (i.e. #) Exit Arrows This box provides just one arrow out to the next step | |
SAY PHONETIC 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 - Text: the text you want to be played: it can be both a digit string (i.e. Joe) or a VARIABLE (i.e. {CALLERID(name)}) - Escape digits: special character to exit from the playing (i.e. #) Exit Arrows This box provides just one arrow out to the next step |
Recordings
The following section allows to perform live recordings of calls.
RECORDDescription This box performs a .wav call recording to a file of the current Asterisk channel Parameters • Label: here you can type a brief box description • Filename: name of the file where you want the recording to be stored** • Escape digits: special digits to exit the current recorded call • Timeout: maximum recording duration in seconds. If -1 the considered timeout is unlimited Exit Arrows This box provides just one arrow out to the next step |
** 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.
Integrations and DB
This groups provides the capabilities to connect the IVR application with a remote DB Schema, so to perform queries and operations.
DATABASESDescription This box lets you perform a query to a DB schema. You must define a DB connection according to the instructions (see please the “Adding a database connection” section)Parameters Label: here you can type e a brief description Database: select the DB you want to connect to Query: here you can perform a DB query (SQL statement) Variable: here you can choose a variable from a pick up list where you want to store the query results. Please consider the variable is a matrix where the columns are mapped to the fields you put in the SELECT clause of your SQL statement, and the rows are the records returned by the query. The first row is addressed with the 0 index and the next ones are addressed with 1, 2, etc, etc 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] Exit Arrows This box provides just one arrow out to the next step |
Built-in variables We provide the following Asterisk channels variables named SHUTTLE[ROWS][COUNT] :shows the number of affected rows (only for SELECT statements). SHUTTLE[AFFECTED][ROWS] : shows the number of affected rows (for INSERT, UPDATE and DELETE statement). SHUTTLE[INSERT][ID] : shows the last inserted id (for INSERT statement). |
SMSDescription This box lets you send a SMS to the specified phone number. Before using this block, please configure the SMS Connection under the SMS section.Parameters Label: here you can type e a brief description SMS: the SMS connection Phone: here you have to set the Phone number that will receive the SMS. Default is {CALLERID(num)} Important: please take a look at your provider specifics for the format of the phone number! (For example some providers need the international prefix)
Text: here you can write the text of the SMS (limit of 160 chars). 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
· Etc…
GOTODescription This box lets you divert the call to another object like · Another IVR application · A queue rule · A fixed extension Generally speaking a specific Asterisk contextParameters Label: a brief description of the box Context: here you can put a context name (check asterisk documentation for the “Context” definition). If you use Cally Square combined with xCALLY this should be: - A rule name - An agent - A DID Extension: in many cases it may be “s”, however you can place the extensions according to your dialplan needsExit Arrows This box provides just one arrow out to the next step |
GOTOIFDescription Perform a conditional jump according to a comparison resultParameters Label: brief description Condition: it is the comparison condition. It could be: o = o < o > o != o <= o >= · Label: brief description · Condition: it is the comparison condition. It could be: o = o < o > o != o <= o >= o || for “OR” and “&&” for “AND” Condition example: '{CHANNEL(language)}' == 'en' || '{CHANNEL(language)}' == 'fr' The above condition is TRUE when the channel language is English or French Exit Arrows For this box you must create two exit arrows using the following values: true: routes to the path in the IVR tree for the condition verified as true false: routes to the path in the IVR tree for the condition verified as false |
SWITCHDescription 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 Variable: the variable you want to read IMPORTANT: you have to specify the variable into curly braces, as shown in the image below.
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. |
NoOpDescription 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 debugParameters Label: here you can type e a short description Exit Arrows This box provides just one arrow out to the next step |
SYSTEMDescription Call an external command or script Parameters Label: brief description Exit Arrows This box provides just one arrow out to the next step |
AGIDescription 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 commandParameters Label: brief description Command: here you can type the command you want the system to execute Arguments: the arguments needed according to the AGI command sytaxExit Arrows This box provides just one arrow out to the next step |
QUEUELOGDescription Thanks to this box you can write a row into the Asterisk queue_log table of the MySQL database. This can be useful for the Queue Statistics, that you can extract in the xCALLY Analytics section. Parameters Label: brief description Queue Name: the name of the Queue Agent: the Agent Event: the Queue event Data 1, 2, 3, 4, 5: the data related to the event Exit Arrows This box provides just one arrow out to the next step |
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 |
CUSTOM APPDescription Thanks to this box you can set your Custom App into the IVR structure. See here an example: Play a sound file based on DID Parameters Label: brief description Application: the application type Options: the options of the application Exit Arrows This box provides just one arrow out to the next step |
Time intervals
Using the Time interval project section and the GoToiftime or Gotoifmutlitime boxes, you can control your IVR call flow based on the time (hours, days, etc...).
GOTOIFTIMEDescription This box lets you take decisions based on the time intervals**Parameters Label: a brief description of the box Time interval: select the time interval pre-defined in the time intervals sections** Exit Arrows For this box you must create two exit arrows using the following values: true: routes to the path in the IVR tree for the time interval condition verified as true false: routes to the path in the IVR tree for the time interval condition verified as false |
GOTOIFMULTITIMEDescription This box lets you take decisions based on the time intervals**Parameters Label: a brief description of the box Time interval: select the multi time intervals pre-defined in the time intervals sections**. Exit Arrows For this box you must create two exit arrows using the following values: true: routes to the path in the IVR tree for just one time interval condition verified as true false: routes to the path in the IVR tree for all the interval condition verified as false |
**Time intervals must be configured using the proper Time Intervals section in the project dashboard
Text-to-Speech
GOOGLE TEXT-TO-SPEECHDescription This box lets you perform a Text-To-Speech translation using the Google TTS Agi*Parameters Label: here you can type a brief description Text: the text you want to be translated Language: the language you want use for the translation (i.e. it, en, etc..) 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. If you need to use a professional Asterisk TTS, please consider the use of another specific TTS provided by specialized companies (i.e. Lumenvox, Vestec, etc... etc...) Use the Google TTS at your own risk! |
ISPEECH TEXT-TO-SPEECHDescription This box lets you perform a Text-To-Speech translation using the Ispeech TTS Agi* Parameters Parameters Label: here you can type a brief description Text: the text you want to be translated Key: your acquired license key from the ispeech.org account Language: the language you want use for the translation (i.e. it, en, etc..) 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. Use the Ispeech TTS at your own risk! |
ISPEECH ADVANCED-VOICE-RECOGNITIONDescription This box lets you a voice-to-text translation using the Ispeech ASR Agi* Parameters Parameters Label: here you can type a brief description Key: Your acquired license key from the ispeech.org account Model: the grammar of the dictation, to increase the precision of the recognition Language: the language you want use for the translation Exit Arrows This box provides just one arrow out to the next step The ASR save the results in two channel variables: utterance: the result of the dictation recognition precision: the precision of the recognition, between 0 and 1. Usually values above 0.8-0.9 means that the dictation has been correctly recognised. 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 behaviors. Each dictation processing require 1 credit. Use the Ispeech ASR at your own risk! |
AWS POLLY TEXT-TO-SPEECHDescription This box lets you to perform a voice-to-text translation using the AWS Polly*. Mandatory: Please see here how to Install AWS Polly. For additional information see https://aws.amazon.com/polly/. Parameters Label: here you can type a brief description Access Key ID and Secret Access Key: AWS security credentials. Required: Yes (see http://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) Region: AWS regional endpoint. Required: Yes (see http://docs.aws.amazon.com/general/latest/gr/rande.html#pol_region) Voice: the voice used for the synthesis. Required: Yes Text: input text to synthetize. Required: Yes Exit Arrows This box provides just one arrow out to the next step |
*In order to have this box working you must have the internet connection
Sub Projects
The following allows you to call for another pre-defined Cally Square project inside the current project. It’s useful to mange complex projects, so you can make separate simpler projects and recalling them inside a main one.
SUBPROJECTDescription This box calls another Cally Square project inside the current oneParameters Label: here you can type a brief box description Subproject: name of the Cally Square project you want to recall inside the current oneExit Arrows No Exit Arrows |