An HTML5 Drag and Drop Asterisk IDE
The following guide describes how to use the Cally Square IVR suite, in order to design IVR applications for your Asterisk based telephony system.
Cally Square provides an IDE environment entirely HTML5 Web Responsive interface, to:
Cally Square is designed to connect via your Asterisk dialplan through a standard AGI interface, providing almost independence from the Asterisk release, easy to be integrated with existing deploymnets and scalability for high performance requirements.
Cally Square is tested on Linux CentOS servers with Asterisk 11.X. However it is a general purpose application, so it should be running fine on several Linux distributions and different Asterisk releases.
Cally Square is a module available inside the xCALLY Shuttle interface (see please here to TRY or BUY)
In order to install and activate Cally Square on your Linux server, please follow the official xCALLY-Shuttle guide received by email (please contact your account manager for more infos).
Browse on the xCALLY-Shuttle Web interface and check the Settings section - Asterisk Manager subsection.
You will see the below information. Click on the Check Connection... button.
You MUST get the below message Connection Asterisk Manager verified!
In case you get error to the Asterisk manager connection, double check again your manager.conf configuration and restart asterisk.
If you want you can change the default manager user and password. The very important point is you use the same user/password information inside the manager.conf file and inside the xCALLY web GUI Settings, Asterisk Manager section.
Remember to restart asterisk if you change any manager.conf user/pwd
CallySquare can be esily installed on your own Asterisk server using the Cally Square installation package.
After the installation has been performed, open your internet browser and type the address of your server.
The login form is displayed
Type in your credentials. Then you can access to the xCALLY Shuttle Dashboard.
Cally Square is accesible via the main xCALLY Shuttle Dashboard Menu.
You can check the role with which you are logged-in.
The available Cally Square roles are:
· Administrator: you can read and write all the system projects. You can also assign the project to different users. Administrator can also change the general system settings.
· User: you can read and write ONLY the projects you have created on your own, or those the Administrator assigned to you
The xCALLY Shuttle interface provides a palette menù on the left sidebar and a design area on the central-right work space.
The main dashboard looks like in the picture below.
Here you can find the IVR project list and the button to create a new IVR.
For each project you can perform the following actions:
By entering the Edit area you can access to the following dashboard.
The dashboard comes with following functional areas:
By clicking the button New Sound + you can upload an audio file to be included in your application.
The system opens the following popup:
By clicking Save you can upload the file to the system.
On the Sounds section you can also:
In this section you can add variables to the project. Variables can be used in the IVR application for several purposes, like:
In order to add a variable you have to fill the pop up:
o Global: it is an Asterisk variable able to to be inherited indefinitely by channels created by the main and subsequent channels
o Channel: such kind of variable lives into a single channel and it is not inherited by any child subsequent channels
When defined, you can Save the current variable. To exit the form without defining any variable click on Close.
Using this capability you can connect your IVR application to a remote DB (Data Base) to read and write data from and to the IVR application itself.
In order to define a DB connection you just need to provide the following information inside the popup:
In order to save the configuration press Save Changes. To exit without any change press Close.
The Cally Square design area is the application core: you can use it in order to design your IVR, expoiting the benefit of a pure Web Drag and Drop HTML5 based interface.
The working area is sliced in two main sections:
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.
This group - start, finally and end - manages the begin and the end of a call from an Application prospective.
|
Description The Start box has to be the very first box in every IVR application. The application will not be published withut 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 |
|
Description This box is executed when the application looses 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. Parameters Label: here you can type a brief description of the boxExit Arrows This box provides just one arrow out to the next step |
|
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 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 |
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.
|
ANSWER
Description 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 |
|
HANGUP
Description This box hangs up the call to the customer on the remote partyParameters Label: here you can type a brief description of the boxExit ArrowsThis box has got any exit arrow |
|
INTERNAL DIAL
Description This box performs the standard Asterisk Dial command towards an internal phoneParameters 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 DIAL
Description 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). |
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).
|
Description 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 |
The following box provides the voicemail command features, in order to route your call flow to a pre-defined Asterisk voicemail box and context.
|
Description 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 |
|
Important: 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 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. Exit ArrowsThis box has got one exit arrow |
In this application, we want a waiting customer to be routed to a call back menu option after X second queue timeout. The following figure shows implementation of this application.
- In the queue setting, we set the timeout (time in seconds a call will wait in the queue before it is routed to the next step).
- In the menu, we insert the name of audio file to be played and we set appropriate values to response timeout, max digit and retry.
- In the call back configuration, we need to insert the phone number of the customer (CallerID: default) and name of a file where the phone number will be inserted (See list creation on Tigerdial).
In this scenario, the caller will be routed to a call back menu if the number of calls waiting is greater than a sepecific value. Here, we use the function QUEUE_VARIABLES(queuename) which makes the variable QUEUECALLS
i.e. number of calls currently in the queue available.
Note: we can also use the function QUEUE_WAITING_COUNT(queuename) which returns the number of callers currently waiting in the specified queuename.
- We use Set box to set value of a variable to the return value of QUEUE_VARIABLES(queuename). By doing this, we can now use the variable QUEUECALLS
.
- GotoIf application is used to direct the call to the menu if the condition (number of waiting calls > 1) is true or to the queue if the condition is false.
- In the call back configuration, we need to insert the phone number of the customer and name of a file where the phone number will be inserted.
Like the previous example, the caller will be routed to a call back menu if the number of calls waiting is greater than a sepecific value. But the customer will insert his phone number manually.
- All part is the same as the previous example except after the customer press 1 to leave their number, we use another menu to request the customer to enter his/her phone number. In the menu configuration, we need to set max digits to length of a phone number and choose a variable that will store digits pressed by the customer.
- In the phone field of call back application, we insert the value of the variable that contains customer’s phone number instead of the default.
The following IVR lets a customer to enable or disable a callback application inside another IVR by pressing 0 or 1 from a menu option.
?
A system application can be used in IVR to send an email notification whenever an inbound call is received. The following example show a simple IVR where an incoming call is routed to a menu option.
echo -e " This is the Body" | mail -s "This is the Subject" -r "<sender@example.com>" recipient@example.com
This group of boxes handles the variables.
|
SET
Description 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 slighlty 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.
The math box can handle complex elaborations.
|
MATH
Description 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) 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!
The following section allows to perform live recordings of calls.
|
RECORD
Description
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.
This groups provides the capabilities to connect the IVR application with a remote DB Schema, so to perform queries and operations.
|
DATA BASES
Description 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 fileds 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, etcExit Arrows This box provides just one arrow out to the next step |
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…
|
GOTO
Description 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 |
|
GOTOIF
Description 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 |
|
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: 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. |
|
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 debugParameters: Label: here you can type e a short description Exit Arrows: This box provides just one arrow out to the next step |
|
SYSTEM
Descrtiption: Call an external command or script Label: brief description 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 commandLabel: 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 |
|
QUEUELOG
Description 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. 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. Label: brief description Goal Name: the name of the goal Exit Arrows: This box provides just one arrow out to the next step |
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...).
|
GOTOIFTIME
Description 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 |
|
GOTOIFMULTITIME
Description 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
|
GOOGLE TEXT-TO-SPEECH
Description 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-SPEECH
Description 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-RECOGNITION
Description 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! |
*In order to have this box working you must have the internet connection
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.
|
SUBPROJECT
Description 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 This box provides just one arrow out to the next step |
In order to design the IVR flow, you have to connect the boxes each other using arrows, like in the picture below.
Please use the following procedure: when you move the curson on to a box, the yellow arrow apperas. Click on it and drag the mouse keeping the left button pressed. Go over the box you want to connect and release the left button.
The two boxes are connected now.
All the boxes wait for at least one arrow in (except the Start and Finally box) and all the boxes wait for at least one arrow out (except the Hungup and End boxes).
When you use the menù or background or any other box requiring a label on the branch, you just need to double click on the branch to add the labels (a text box will appear and you will be able to add the labels).
The design area comes with a toolbar located on the top header.
· Save : save the project to the local file system. Please keep in mind when the project is just saved it is still not active on the production asterisk system
· Publish : publish the project to the remote system. If the project is published with no errors you can consider it active and it can be used in your asterisk telephony system
· Print : IVR tree preview for an hardprint
· Undo/Redo : undoes or redoes the last action on the application
· Trash : deletes the selected boxes
· Copy/Cut/Paste copies, cuts or pastes the selected boxes into the clipboard
· Actual SIze/Zoom in/Zoom Out : resize the design area or restore the original size
Once your IVR application has been saved and published without errors you can use it with your xCALLY system.
Go to the Dial Plan section, create a new Route and associate to this route the IVR-Cally Square application.
In order to call one Cally Square IVR project inside your Free PBX system just perform the following steps:
?
For example fill in with:
csquareivr1,s,1
c. Fill in a description in the Description field
d. Click on Save
e. Browse under the Connectivity section à Inbound Routes and select your existing inbound involved route (or create a new one if you need)
f. Reach the bottom of your inbound route page and select Custom Destination in the pick-list field.
g. Select the previously created custom destination (see below screenshot)
Connect to your Linux FreePBX system console (i.e. via ssh) and add the following lines inside the file
/etc/asterisk/extensions_custom.conf
[csquareivr1]
exten => s,1,NoOp(Inbound IVR Cally Square calls)
exten => s,n,AGI(agi://127.0.0.1/square,project=6)
reload Asterisk
asterisk -r
dialplan reload
You are done!
In the following paragraphs you can find some IVR tree examples.
This kind of IVR Applications is used to dispatch calls to different agent queues. For example your call center provides different services:
· Press 1 if you want billing informations
· Press 2 if you want to check your order status
· Press 3 for general inquiry
The application has to collect the choice from the customer so to route the call to the appropriate queue.
In the picture below you can see a tree example:
Analyzing the Tree you may notice when a call gets into the system it performs the following steps:
· The Start box initializes the call flow
· The Answer Box answers the voice channel
· The Menu Box plays the message according to the option menu
· If the customer makes a valid choice, the Appllication routes the flow to one of the GoTo boxes
· The GoTo Boxes contain the context name to which the call will be routed
In the following picture you can see how the menu box can to be configured, in order to make the application working as described.
The GoTo box routes the call to the RR-BILLING context. In this context you can call a queue, embed a new IVR, route the call to a fixed extension, or proceed in your Asterisk dialplan as you prefer.
In the following picture you can see how the GoTo box has to be configured in order to make the system working as described.
In the following example you can learn how to build a DB interaction between the IVR application and a remote DataBase.
Here we imagine to make a SELECT FROM WHERE Sql statement inside a post call handling routine using the Finally Box.
First of all you let’s define a new Channel variable inside the project dashboard.
Then we need to declare a connection to an existing DB
In our example we would need to query the table below (tableX):
The query we have performed is:
SELECT field1, field2, field3 FROM tableX
The whole returned resultset is stored in the RESULTSET defined variable.
To retrieve the value of a single field in a row you have to use the following notation (in our example by a NoOp box)
RESULTSET[#row][field_name]
Where:
#row: the row number in the resultset. Note that the row numbering start from 0
field_name: the name of the column as named in the DB schema
Q. I always get a Congestion message error on the Asterisk IVR, even if I have properly setup the Cally Square AGI in the dialplan:
csquare.php,Demo: THE CONNECTION IS NOT AVAILABLE!
A. Check the Asterisk Manager connection. In order to have Cally Square properly working you need the manager.conf properly configured with manger enabled (enabled=yes) and a valid user to get Cally Square connected:
This is the default Cally Square manager user:
[xcall]
secret = xcall1234
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.255
read = all
write = all
Check on the xCALLY-Shuttle web interface under the Settings menù to verify you are connecting to the same user available in manager.conf
You can TRY and BUY the Cally Square solution using the Cally Square SHOP here avaiable
Cally Square and xCALLY are Xenialab Trademarks
Asterisk is a Digium Trademark