Cally Square

User Advanced Guide

• created: 03/10/2014
• latest update: 11/04/2015
• by: The xCALLY-Shuttle TEAM
• email: callysquare@xcally.com

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:

• Manage your Projects
  - Design your IVR using a Drag and Drop technology
  - Managing your IVR, from simple auto-attendand to complex scripting tools

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:

• Edit the general project settings and enter the project Design area by clicking on 
• Delete the project by clicking on  

By entering the Edit area you can access to the following dashboard.

The dashboard comes with following functional areas:

• General: displays the general project settings (name and description)
• Variables: section to define, add or edit the variables to be used by the IVR application
• Databases: in this section you will tell the system how to connect to the remote DB (useful when you want to build DB driven IVR applications)
• Time Intervals: where you can define time intervals on which the IVR is active
• Sounds: here you can upload the audio files for your IVR application
• Recordings: here you can find recorded calls
• Design: in this section you can design the IVR structure thanks to the drag and drop interface.

By clicking the button New Sound + you can upload an audio file to be included in your application.

The system opens the following popup:

• Name:  type the name for the file to refer to into the IVR application. Please avoid spaces and special charachters
• Description: you can type a short file description
• File: by clicking Select you can locate an audio file on you local file system

By clicking Save you can upload the file to the system.

On the Sounds section you can also:

• Download the audio file: note that you will download the audio file converted in the format that fits the Asterisk System needs;
• Listen to the audio file preview;
• Edit or Delete the audio file.

In this section you can add variables to the project. Variables can be used in the IVR application for several purposes, like:

• Dinamically change the application flow;
• Read or write data in a database table or managing Asterisk variables;
• Store the customer pressed digits and codes...

In order to add a variable you have to fill the pop up:

• Variable Name: the name you want to use to refer to the variable
• Type: the variable can be:

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

• Description: here you can provide a short description about the meaning or usage of the variable you are defining.

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:

• Database: database name you would like to connect to.
• Host: the server IP of the database
• Username:  DB username
• Password: DB password
• Confirm Password: DB password confirmation
• Type: indicates the driver to perform the DB connection. Currently just Mysql.
• Description: here you can provide a short description

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:

• A tool palette from which you can choose the developing tools to implement the IVR (mainly Asterisk key applications and more specific Cally Square value added applications);

• The design area where you can drag and drop the boxes from the tool palette.

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.

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.

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).

The following box provides the voicemail command features, in order to route your call flow to a pre-defined Asterisk voicemail box and context.

- 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).

Call Back IVR [N_queue calls and caller number auto-recognition]

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.

Call Back IVR [N_queue calls and caller number manual insertion]

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.

Enable/Disable callback

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.

• First create a new database in MYSQL (Must be different from XCALLY DB). Then create a new table with two columns. Column 1 can be ID, Column 2 can be ANY_NAME.
• Go to XCALLY web interface and create a IVR project

• In the menu, insert the audio file to be played and we set appropriate values to response timeout and number of retry. We need to select a variable that will store the option selected by the caller. 0 to disable and 1 to enable call back.

• Insert a new database detail

• Under integration Server, add database and edit
  • Query: UPDATE table_name SET column2=value WHERE column1=some_value;

               ?

• Inside the Callback IVR

• Insert a new database detail

• To access the value from the database
  • Query: SELECT  column2  FROM table_name  WHERE column1=some_value;
  • The query result is stored in the variable Choice

• To retrieve the value inside the variable:  {Choice[#row][column2]}
• In the GotoIf application we insert the condition. If the condition is false the call goes straight to the queue. (1 means callback is enabled).

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.

• 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. We need to select a variable that will store the option selected by the caller.

• System application: The following is a command for sending email using mailx. (To install mailx use “ sudo yum install mailx”)

 echo -e " This is the Body" | mail -s "This is the Subject" -r "<sender@example.com>" recipient@example.com

•  Body message : " Caller Number: {CALLERID(num)}   Choice: {CHOICE}   Call Time: {CDR(ANSWER)} "
• Subject : "Caller Info"

This group of boxes handles the variables.

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.

** 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!

This group manages the audio playing.

The following section allows to perform live recordings of calls.

** 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.

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…

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...).

**Time intervals must be configured using the proper Time Intervals section in the project dashboard

*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.

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:

1. Browse the administration FreePBX web interface under the Admin section and select Custom Destination.
2. Fill in the Custom destination field with context,extension,1

?

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

www.callysquare.com