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
Import and export an application
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.

Visual Designer Application Architecture

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.

Visual Designer Verbs

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 to Collect 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 variable Scope. 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 the Continue 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 the Validation 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, choose Menu.
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.

Pause Verb

Pause makes it possible to add a pause in seconds between different Say announcements.

SMS Verb

SMS makes it possible to send a message from one phone number or client to another.If the text of the message exceeds 163 characters, the text is split.Optionally you can set a Status callback URL.This verb can be used both in Voice and SMS applications.

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.

Accessing the Visual Designer Application Logs

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.

Deleting Visual Designer Application Logs

You can delete your application logs by clicking on the Reset button in the Logs console screen.

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

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 the User 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.

Learn More

Find out more about RCML and how it can help bring additional functionality to communications applications.

Visit the REST API documentation to discover the various types of requests and how to use them to take new ideas from concept to reality.