Visual Designer Usage Guide
Overview
The CPaaS Visual Designer is an easy to use graphical tool that enables non-programmers to design and manage telecommunications applications.Drag and drop actions to support the quick development of a wide range of Voice & Messaging applications.A set or series of actions and operations can be saved as a package to be shared and reused in other, more sophisticated applications and services.
For example, one can start with a simple call flow in which an incoming call to a specific phone number is received and routed to a recorded message.You can then create an interactive voice response (IVR) menu.From the menu, you can allow callers to leave a voicemail, send them an SMS, or forward the call to different phone numbers or agents.In addition, you can use Visual Designer modules to integrate and automate calls to a customer from a third-party platform (CRMs, marketing automation tools, support portals etc).It is also possible to retrieve customer information from a database and send targeted A2P (Application-to-Person) marketing messages by SMS using your favorite programming language.
The Visual Designer environment makes fast work of prototyping your telecom applications on the CPaaS platform.You do not need to develop a custom client to test your applications. CPaaS comes with a WebRTC Demo, which helps you do that quickly.Diagnostics and logging tools for generated code and call attempts provide clear visibility in the output of each step during the development process.
Who Can Use Visual Designer
Visual Designer can be used by anyone at your organization to create their own applications or use ready-made ones from the Template Gallery.
Visual Designer Features
-
Design and customize an application
-
Execute an application via inbound voice call, SMS, or Web Trigger
-
Create and pass application or module variables
-
Make routing decision based on a variable value
-
Monitor and troubleshoot application modules through the application log
Getting Started
You can start using Visual Designer by navigating to your CPaaS Console
→ Applications
→ +Add New App
then clicking on the Create Visual Designer application
button.

Main Components
Below you can find out more about the main components of Visual Designer and how they can be in handy for you.
Application
An Application is the main Visual Designer entity.It represents your project and consists of modules and verbs.There are two types of applications you can build - Voice, SMS.Each application can have as many modules and verbs as you would like.
Modules
Modules are the main Application components. Each one of those consists of a minimum one verb. There is no limit on the amount of modules used within an application as long as their names are unique. Modules are collections of programming statements and commands that use the CPaaS APIs. This means that programmers can reuse the commands and APIs available with other programming languages as desired. In addition, it is easy to incorporate input and output from external services.
Verbs
Verbs are the main Module’s components.A verb can trigger a single or multiple actions within a Visual Designer application.For example, a Collect verb can play an announcement to the user and also collect DTMF input.Often one and the same verb can be used multiple times within the same application module.Most of the verbs have a set of required configuration settings you must set up in order for those to be executed.
If required configuration fields are left undefinedunset, the application will be saved with validation errors and will not function properly. |
Actions
Actions are triggered when an application is executed.The number of actions varies based on the verb(s) used in an application module.In some cases multiple actions may be triggered for a single application module.For example, a DTMF input can be gathered using the Collect verb and assigned to an application wide variable.

Designing Your Visual Designer Application
The variety of verbs inside Visual Designer makes it possible to build applications that cover various business functions.Before diving into the designing process make sure to first get familiar with each of the verbs capabilities.That will help you determine the right application design and save you time while designing.
Say Verb

The Say verb is one of the most commonly used within voice applications.It lets you play an announcement to the user.You can select the Language and voice type (male/female) for it, as well the number of times you want the announcement to be repeated.Say can be used alone or in combination with Collect.
Play Verb


Play verb allows you to play media files to the application user.You can choose between playing .wav files uploaded directly within your application or select one from the ready made URL wav files library.
If you choose to play a media file uploaded within your project, be aware of the required media file format. |
Collect Verb
The Collect verb makes it easy to create IVR menus, gather DTMF input from the caller, and execute a followup application module.
DTMF input can be gathered in two ways: by assigning the digit pressed to an application or module available variable, or by mapping it to an application module that will be executed next.
Assigning DTMF Input to a Variable
-
Drag and drop a Say verb inside Collect.Use the Say verb to create an announcement with options that will be played to the caller.
-
Click on the gear icon and select the language in which you would like the announcement to be played.
-
Set the number of times you would like the announcement to be played in the
Repeat # times
field.Leave it blank if you would like to play it only once. -
Under
Create a menu or collect digits
section, choose toCollect digits.
-
Next, you need to give a name to the variable under which the DTMF will be stored.Enter the desired variable name in the
Assign to
field.Define the variableScope.
You can either make it available for the whole application or for this particular application module. -
Once the input is gathered and stored under a variable, the app will proceed to a
Continue to
module.Make sure to select the proper followup module from theContinue to
drop down. -
Optionally you can play a message to the caller if no input has been received.
-
In addition, you may specify a
Validation pattern
.Either as an array of values to validate from or using a regex expression.You can set the validation pattern type from the drop-down next to theValidation pattern
input field. -
If the validation pattern fails, a message can be played to the caller.That can be added under the
Say if invalid
field. -
In some cases you may want to let the caller end the call by pressing a particular digit.You can specify that under the
Finish on key
field.When that digit is pressed, the application will stop executing further modules and the call will be disconnected. -
Sometimes the caller may press more digits at once than the available options.That will lead to the call being disconnected.To avoid that, you can limit the number of digits pressed under the
Number of digits
field. -
Optionally you can set a module
Timeout
in seconds.If the caller does not press a digit during that time, the call will disconnect.

Collecting DTMF Input
This step assumes that you have already specified the Say announcement to be played to the caller inside Collect.Set the desired language and number of times you would like the announcement to be played.
-
Under the
Create a menu or collect digits
section, chooseMenu.
-
Next, map Digit option to the Target module which will be executed next once the DTMF is received.
-
Make sure to map all the Digit options with their corresponding Targets.If a Target is left blank, the application will not execute further and the call will be disconnected.
-
You can play a message to the caller if no input has been received.
-
In addition, you may play a message to the user if the Validation fails.You can enter that in the
Say if invalid
field. -
In some cases you may want to let the caller end the call by pressing a particular digit.You can specify that under the
Finish on key
field.When that digit is pressed the application will stop executing further modules and the call will be disconnected. -
Sometimes the caller may press more digits at once than the available options.That will lead to the call being disconnected.To avoid that, you can limit the number of digits pressed under the
Number of digits
field. -
Optionally you can set a module
Timeout
in seconds.If the caller does not press a digit during that time the call will disconnect.

When using Collect make sure to properly map digits option with Targets and set Continue to modules when necessary.Missing digits mappings will result in errors while trying to save your application and malfunction of the application. |
Dial Verb

The Dial verb helps you connect a caller to another party.You can dial a phone number, SIP client, SIP URI, or a conference room.When the dialed party answers the call, the two call participants are connected and may communicate until one of them disconnects.
A call will end if:
-
the called party does not pick up
-
the called party is busy
-
The dialed number is invalid or out of reach
Before Connect
Within the Dial verb you may want to set a Say message from another application module to be played to the caller while waiting to be connected.
StatusCallBack
You may set a StatusCallBack URL or module to pass along the status of the Dial attempt.For more information about the possible Dial attempt statuses, please check out the Dial RCML documentation.
Caller ID
When dialing a number you may want to set a Caller ID to be displayed to the called party.For example, if you are dialing +12223334444 with Caller ID +16667778888, the called party will see +16667778888 as caller ID of the incoming call.The Caller ID can take the value of a phone number, as well as any core or custom Visual Designer variable.
CPaaS supports setting up a Caller ID for Numbers and Conferences only. |
Timeout
With Dial you can set a dial connection timeout in seconds.When the specified period of time expires, the connection is terminated.
Time limit
Time limit helps you set the length of a call in seconds.When the specified period of time expires, the call is terminated.
Continue to
You may want to execute another application module once the call is completed.To do that you can simply choose the desired module from the Continue to drop-down menu.
Record
If you would like to record calls you can select the Yes
option from the Record drop down.
Recording of Conference calls is not supported. |
Ringback tone
The Ringback tone lets you change the default dial tone to a .wav file hosted in your application or public service.
Redirect Verb


The Redirect verb lets you redirect the user to another application module or a URL application.The allowed methods for URL applications are POST and GET.Redirect can be used in both Voice and SMS applications.
Hangup Verb

Hang up allows you to disconnect the call.If used as a first verb in your application it will result in answering the call and immediately hanging up after.If you would like the call to be unanswered, use the Reject verb instead.
Reject Verb

Reject lets you reject a call for a particular reason.Possible options include: busy, rejected, forbidden, anonymity_disallowed, address_incomplete, no_route, service_unavailable, unwanted.Reject can be used when you do not want to answer a call and avoid additional billing of your account.
Email Verb

Email verb enables you to send emails via your Visual Designer application.You can set the email body, subject, sender, and recipient email addresses.Optionally you can add CC and BCC recipients.Email can be used in both Voice and SMS applications.
Record Verb

You may wish to record voice messages while you are unable to pick up the phone. Record lets you play a beep before the recording starts.Optionally you can put a timeout and maximum length of the messages in seconds.You can also set the finish on key.When the user presses it the recording will end.In addition, you must specify Continue to module.For example, when you would like voicemail to be sent to your email address.
Control Verb
The Control verb performs basic tasks based on a set of conditions.It is the equivalent of if-then control structure in developer terms.Control consists of conditions and actions.If the conditions are met, the actions are executed.
Conditions
You can create conditions using multiple operators or regex expressions.
Available operators include:
-
Equal
-
Not equal
-
Greater
-
Greater or equal
-
Less
-
Less or equal
-
Regex match

You can compare two operands either as a text (ABCD) or as numbers (1234).For numeric comparison, the operands shall be convertible to numbers.Floats are supported.For text based comparisons any operand will work.You can switch between comparison types using the ABCD/123 link right after the operands input fields.
Be aware while working with operands that numbers or text will not always render the same result.For example 4 is not greater than 05. At the same time '4' is greater than '05'.Make sure to always use the correct comparison type. |
Regex Match
Regex match attempts to match a string (or a portion of it) to the regular expression specified in the pattern parameter.If a match is found it evaluates to true.

Handling Multiple Conditions
More than one condition can be evaluated within the Control element.When multiple conditions are set, each one of them will be evaluated individually and the results will be combined to determine the status of the whole complex condition.This can be achieved in two ways.Either All conditions should stand (AND operation) or Any condition should stand (OR operation).
In case no condition is present, the Control element will evaluate to true and the following actions will be executed. |
Actions
Actions represent a number of tasks that are sequentially executed if the condition(s) evaluate to true.Three types of actions are available to use: Assign, Capture, and Continue to.
Capture
You can capture part of a string according to a specified regex pattern and assign the captured value to a variable.Make sure to use a pair of parentheses to designate the captured segment.The use of a single pair parenthesis is obligatory inside the pattern parameter.In addition, only literal regex patterns are supported.

Assign
The Assign action lets you create a variable and assign a value to it once the Conditions are sequentially executed.It can be available either within the same application module or the whole application.

Continue to
With the help of Continue to you can specify which application module shall be executed next.

Make sure to only include a single Continue to action in a Control element and always make it last.If Continue to is not last, the action specified afterward will not be executed.The application will continue to another module instead.You can alter the order of actions using the reorder button on the right of the action row. |
External Service Verb
External Service is one of the most powerful Visual Designer verbs.It can be used as a tool for making HTTP requests to external services and processing their responses.The following functionalities are supported within Visual Designer:
-
GET or POST request methods
-
JSON or web form content types
-
HTTP or HTTPS schemes
-
Basic HTTP authentication
External Service GET Request

By default all requests are using the GET method.Note that name-value parameter is user defined.Such parameters are appended in the query when the request is made.It is a good practice to keep the service parameters in their own fields rather than putting them directly in the Service Url field.
Request Example
GET /services/simpleGetRequest?name=foo HTTP/1.1 Host: yourdomain.com Response: HTTP/1.1 200 OK
Variable Expansion
Both Service Url and Value fields support variable expansion. That means that all $variables and references to them will be replaced by their actual value before the request is being made.
For example:

Here the $firstname
variable will be expanded to its actual content.
$firstname → name
External Service POST Request
To change the default request method you will have to modify the External Service advanced settings. You can access those by clicking on the gear icon below the add service parameter
button. Select POST from the Method drop down. Then set the content type to www-form or json. If you wish, you can manually add the POST body in the text area below.

Note that the service parameters will be ignored if url-encoded request body is provided. If you are entering a JSON body, make sure to use double quotes. For example:
{"firstname":"$firstname","lastname":"bar"} . Visual Designer cannot differentiate between the various JSON types. Therefore it runs a search and replace. The goal is to ensure that a valid JSON expression is generated in the end.
|
Request Example
POST /services/simplePostRequest HTTP/1.1 Content-Type: application/x-www-form-urlencoded firstname=foo&lastname=bar Response HTTP/1.1 200 OK
Using Basic HTTP Authentication
If a service is using basic HTTP authentication, you will need to additionally provide user credentials, such as username and password as shown below.

Handling Service HTTP Errors
In case your external service is failing you may want to notify the caller about that.You can create an additional application module to be executed when the error occurs.
To do that you can create a new module named Service Error Announcement.Drag and drop a Say verb into it and enter the announcement inside.

Next, get back to your external service module and navigate to the Error & Timeouts section.Select the Service Error Announcement module from the On HTTP Error drop down.Optionally you can set Timeout in seconds after which this announcement will be played to the caller in case of external service failure.Lastly you may want to create an application module with another announcement to be played when Connection errors and Timeouts occur.

Log Verb

Log verb is designed to help you troubleshoot Visual Designer applications.It allows you to add text, refer to application or module variables, and see if those are properly captured in the application logs.If properly captured, you shall see the corresponding variable values printed in the logs.This module can be added to any application module and can be used in both Voice and SMS applications.
Accessing Visual Designer Application Logs
In order to start capturing Application logs you shall first enable that option from the Application settings.To do that, navigate to your application name
→ Settings
.Go to the Application logging
section and click on the check box next to Enable
.Next, select what types of logs you would like to gather.Possible options include: RCML and External Service request and responses.Click Save
.

Once the application logging is enabled you will be able to see logs for each execution of your application.You can access the logs console by navigating to your application name
→ Log
.
Visual Designer Variables
While designing your application you may use CPaaS core variables to retrieve user information that comes from the inbound call or SMS, as well as refer to custom variables introduced within modules that store values and pass those from one module to another.
Core Variables
The Visual Designer core variables are system-defined and can be accessed within most of the Visual Designer verbs by navigating to the Lookup variable dropdown.They can be easily recognized within the customly introduced ones by the core_
prefix of their names.Below you can find more about each variable and what information it retrieves.
Variable Name | Description |
---|---|
core_AccountSid |
Retrieves the corresponding Account SID |
core_Body |
Retrieves the body text of an SMS message |
core_CallerName |
Retrieves the caller name (if specified) |
core_CallSid |
Retrieves the caller Sid |
core_CallStatus |
Retrieves the call status |
core_CallTimestamp |
Retrieves the call time stamp |
core_DialCallDuration |
Retrieves the call duration |
core_DialCallSid |
Retrieves the Dial call Sid |
core_DialCallStatus |
Retrieves the Dial call status |
core_DialRingDuration |
Retrieves the Dial ring duration |
core_Digits |
Retrieves the DTMF input |
core_Direction |
Retrieves the direction of the call |
core_ForwardedFrom |
Retrieves information about from where the call was forwarded |
core_From |
Retrieves the Caller phone number |
core_RecordingUrl |
Retrieves the public URL of a call recording |
core_RecordingDuration |
Retrieves the duration of the call recording |
core_SmsSid |
Retrieves the SMS Sid |
core_SmsStatus |
Retrieves the SMS status |
core_To |
Retrieves the Callee phone number |
Custom Variables
Custom variables are Visual Designer application variables defined by the user.They can be used to collect, store, and retrieve data within a particular module or the whole application.Each variable has to have a unique name.When the scope of the custom variable is set to the whole application, it can be referred to in any of the follow up application modules.
Make sure to reference a custom variable only after its value is set or received as input.If you attempt to retrieve it earlier than that, your application will malfunction and you will not be able to execute the desired application flow. |
Additional Application Settings
Application Diagram
The Visual Designer application diagram is a graphical representation of an application flow.It outlines the connection between the application modules and what their triggering actions are.
You can access an application diagram by navigating to its name inside Visual Designer and then clicking on the Diagram option.


Application URL
The Application URL is the direct URL under which you can access a particular Visual Designer application.It has the following format and can be found by navigating to your application name → App URL.
https://yourdomain.com/visual-designer/services/apps/AP60XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/controller
Web Trigger
Web Trigger offers you an alternative way to start a voice application.It allows establishing a call between the application and a destination address using a simple HTTP request.
Web Trigger is not available to use with SMS applications.However you can build a Voice application with an SMS functionality and use Web Trigger together with it. |
Follow the steps below to enable Web Trigger for your voice application:
-
Open your voice application in Visual Designer.
-
Navigate to your
application name
→Web Trigger
. -
Click on the
Enable
checkbox button. -
If you would like to authenticate the requests with your CPaaS account credentials, leave the Application access token field empty.Alternatively, enter your access token that will be used as an additional request parameter.
-
Optionally you can override the call source and destination addresses of the call by filling out the To and From fields.
The To and From fields are using the RCML Dial syntax.For example: +12223334444 or sip:+15556667777@yourdomain.com
|
-
Click on the
Advanced configuration
gear icon.From theUser parameter scope
drop down, select the application scope for which the From and To parameters will be overridden (either for the whole application or an application module).If left blank those will be overwritten for the whole application. -
Click on the
Save
button. -
Then Save your application changes.
-
Now you can start your application by making a request to the WebTrigger URL using the following format:
https://yourdomain.com:443/visual-designer/services/apps/APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/start?from=+12223334444&to=+15556667777&token=yourtoken

Application Management
Importing an Application
To import an application navigate to the CPaaS Console
→ Applications
→ + Add New App
.Choose to import a Visual Designer Application.Give your application a name, then click Import
.You will be redirected to your application in Visual Designer.

Exporting an Application
To export an application, navigate to the CPaaS Console
→ Applications
.Choose the application you intend to import from the application list.Click on the download
button next to the application name.A .ZIP file of your application will be downloaded to your machine.

Deleting an Application
To delete a Visual Designer application, navigate to the CPaaS Console
→ Applications
.Click on the application you would like to delete and then hit the Delete Application
button.You will see a warning screen similar to the one below.
The delete action cannot be undone.Once you delete the application you will not be able to restore it. |
