Tutorials: Widget Library Definitions
Required access: Voxtelesys Portal
Table of Contents
*Disclaimer: You will need to have Voice API enabled on your account to do this you will need to open a ticket with support. VAST flow builder is still in BETA please keep this in mind are you create your flow.
Last Updated:9.12.24
Start Widget
- Choose whether you want this flow to be based on an Inbound or Outbound Call
These are the widgets under the Voice section in the VAST flow builder.
Answer Call
- For inbound call flows, this widget answers the call. If the call originated via SIP, then a 200 OK is sent to the SIP client. Billing for the call begins once the Answer Call widget is executed. In most flows, the Answer Call widget should be the first executed widget.
Collect Input
- This widget plays an audio file or speaks TTS and then collects a user’s keypresses via dual tone multi-frequency (DTMF) keypresses or voice input via speech recognition. The collected keypresses or voice input is saved to a variable on the call which can be accessed immediately or later on in the flow to control which flow path the user traverses.
If speech recognition is used for input collection, the call is billed for the duration of the speech-to-text (STT) collection in 15 second increments.
Settings
Input (required)
Specifies what type of input to collect from the user. The options are below.
Speech: collects transcribed speech from user
Digits: collects DTMF from
Speech and Digits: collects both DTMF and transcribed speech from the user
Action Type (required)
Specifies the audio source. The options are below.
Play Audio: fetches an MP3 or WAV file from a URL
Say Text: generates TTS
Audio File (required, if Action Type = “Play File”)
The URL of a publicly available MP3 or WAV file. The response Cache-Control header is honored, if provided. To reduce latency caused by download times, it is recommended to provide the Cache-Control header. Once cached, the file will be locally retrieved until it becomes stale.
Say Text (required, if Action Type = “Say Text”)
The text to say to the user. The text is generated using the Language and Voice settings. The length is limited to 3,000 UTF-8 single byte characters, not including SSML tags.
Language (optional, if Action Type = “Say Text”)
The language to be used when generating the TTS.
Voice (optional, if Action Type = “Say Text”)
The voice to be used when generating the TTS. Currently, the integrated TTS engines include: AWS (standard, neural). The convention used for Voice naming is: [<engine>] <voice>(-Neural)?. For example, [Polly] Matthew-Neural uses the AWS Neural engine with Matthew’s voice.
The call is billed for the length of the Say Text, in 100 character intervals. Pricing is dependent on the engine used for TTS synthesis.
Loop (optional)
The number of times to repeat the TTS or audio file.
Number of Digits (optional)
The number of digits to collect from the user before continuing to the Conditions evaluations. This setting is useful when the flow designer knows exactly how many digits are expected. Once the number of digits is met, the widget continues immediately to the Conditions evaluations instead of waiting for the Timeout to be reached.
For example, consider a case where the user is prompted to enter their zip code. In this case, the Number of Digits setting should be set to 5.
Finish on Key(s) (optional)
One or more keys that the user can press to submit their digits and continue to the Conditions evaluations. This setting is useful when the designer wants to allow the user to enter a digit to continue the call flow immediately without having to wait for the Timeout to be reached.
For example, consider a case where the user is prompted to enter a conference room ID followed by the # sign. In this case, if the user enter 1234# then the widget stores 1234 and immediately continues to the Conditions evaluations.
Profanity Filter (optional)
If enabled, any profanities spoken by the user will be filtered by the widget. The filtering is done by replacing all but the first character with an asterisk. For example, “shit” would be filtered by the filter to “s***”.
Timeout (optional)
Sets the duration in seconds that the widget will wait for the user to press another digit or say another word before continuing to the Conditions evaluations. The timeout period does not begin until the prompt has completed. If set too high, the user may experience a long period of silence until the Timeout is reached. If set too low, the user may not have enough time to enter digits or say another word.
Speech Timeout (optional)
Sets the duration in seconds that the widget will wait after a pause in speech before continuing to the Conditions evaluations. If set to auto, the widget will continue as soon as a pause in speech is detected
Connect Call
- This widget allows the user to bridge an in-progress call with another user via the PSTN. The result of the call connection is saved to a call variable: <widget_name>.status.
Settings
To (optional)
The phone number to connect the call to.
Caller ID (optional)
The phone number to use as the Caller ID when connecting the call. The number must be associated with the user’s account ID.
Timeout (optional)
The duration in seconds to wait for the dialed party to answer the call. If the Timeout is reached, then the connecting call is canceled.
Time Limit (optional)
The maximum duration in seconds of the connected call. The connected call will automatically end when the limit is reached.
Ring Tone (optional)
The number of times to repeat the TTS.
Record (optional)
If enabled, the connecting call will be recorded.
Answer on Bridge (optional)
If enabled and the call has not yet been answered, then the call will continue to ring until the dialed number is answered. This setting is only applicable to inbound calls. If the call originated via SIP, then the originating SIP client will not receive a 200 until the connecting call is answered.
Hangup On Star (optional)
If enabled, this setting allows the initial caller to hang up on the called party by pressing the * key. This setting allows the initial caller to hang up on the called party without having to hang up the phone (which would end the flow). Therefore, this widget is useful when the designer wants to execute additional widgets after the connecting call has completed.
Transitions
Completed
Activated if the connected call was answered and completed successfully.
Busy
Activated if the connected endpoint returned a busy status. If SIP is used for call signaling, then this transition is activated if the connected endpoint returns a 486 SIP code.
No Answer
Activated if the connected endpoint does not answer the call. If SIP is used for call signaling, then this transition is activated on a 487 CANCEL.
Failed
Activated in all other failure scenarios. If SIP is used for call signaling, then this transition is activate for 4XX, 5XX, and 6XX response codes.
Hang Up Call
- Ends the call. If the call originated via SIP, then a BYE is sent to the SIP client. Billing for the call ends once the Hang Up Call widget is explicitly executed. If the call is completed by another method (user manually hangs up, API, etc) then the call will be terminated and billed even if the Hang Up Call widget is not executed.
Pause Call
- This widget injects silence into the call and pauses for the provided duration. This widget is useful when the designer wants to wait before playing a prompt, such as during a menu loop.
Settings
Length (optional)
The duration in seconds to pause the call.
Record Voicemail
- This widget is used to record voicemail audio from the caller.
One or more keys that the user can press to end the recording. Multiple keys can be provided and act as an and condition. For example, if set to #* then the user can press either # or * to end the recording.
Max Length (optional)
The maximum duration in seconds of the recordings. For example, if set to 120 then the widget will automatically end the recording after two minutes.
Play Beep (optional)
If enabled, the widget will play a short beep before starting the recording.
Recording Status Callback URL (optional)
The URL of a publicly available HTTP endpoint. If provided, then the widget will send status update webhooks to the URL. For more details on the webhook payload structure please refer to the Voice API documentation.
Recording Status Callback Method (optional)
The HTTP method to use when sending callback(s) to the provided URL. The options are POST and GET. For more details on the webhook payload structure please refer to the Voice API documentation.
Say/Play
- This widget plays an audio file, says text-to-speech (TTS), or plays DTMF tones to the user.
If playing an audio file, the URL must be publicly available and return an MP3 or WAV file. Additionally, the response Cache-Control header is honored if provided. To reduce latency caused by download times, it is recommended to provide the Cache-Control header. Once cached, the file will be locally retrieved until it becomes stale.
If playing DTMF tones, the tones will be injected into the call which can be useful when testing IVRs with a known call flow structure.
This widget converts text to speech (TTS) and plays back the generated audio to the user. Currently supported TTS engines include AWS. The call is billed for the length of the Text, in 100 character intervals. Pricing is dependent on the engine used for TTS synthesis.
Settings
Action Type (required)
The type of audio to play to the user. The options are below.
Say Text: plays text-to-speech to the user
Play Audio: plays a file from an URL to the user
Play Digits: plays DTMF to the user
Language (optional, if Action Type = “Say Text”)
The language to be used when generating the TTS.
Voice (optional, if Action Type = “Say Text”)
The voice to be used when generating the TTS. Currently, the integrated TTS engines include: AWS (standard, neural). The convention used for Voice naming is: [<engine>] <voice>(-Neural)?. For example, [Polly] Matthew-Neural uses the AWS Neural engine with Matthew’s voice.
Text (required, if Action Type = “Say Text”)
The text to say to the user. The text is generated using the Language and Voice settings. The length is limited to 3,000 UTF-8 single byte characters, not including SSML tags.
URL (required, if Action Type = “Play Audio”)
The URL of a publicly available MP3 or WAV file.
Digits (required, if Action Type = “Play Digits”)
The DTMF tones to inject into the call. Additionally, if the character “w” can be used to inject 0.5 seconds of silence. For example, 12ww34 would result in the following tone injection: 1, 2, a second of silence, 3, and 4.
Loop(s) (optional)
The number of times to repeat the audio file.
This is the widget under the Messaging section in the VAST flow builder.
Send SMS
- This widget sends an SMS message.
Settings
Service Trunk Group (required)
The duration in seconds to pause the call.
To (required)
The phone number to send the message to.
From (required)
The phone number to use as the Toll Free Number or 10-DLC when sending the message.
The number must be associated with the provided Service Trunk Group and must be an enabled Toll Free Number (TFN) or 10-DLC.
Message Text (required)
The text to send in your message.
These are the widgets under the tools section in the VAST flow builder.
HTTP Request
- This widget allows the designer to interact with external web applications. For JSON response payloads, the data is parsed and accessible via call variables in subsequent widgets. The parsed variables are accessible via the <widget_name>.parsed variable prefix. For example, if the response JSON is {“make”:”volkswagen”,”model”:”jetta”,”year”:”2000”} then to access the JSON year field the designer would use <widget_name>.parsed.year.
Settings
URL (required)
The URL of a publicly available web application.
Method (required)
The HTTP method to use when sending callback(s) to the provided URL. The options are POST and GET.
Content Type (required)
The content type of the request payload. Options are application/json, application/xml and application/x-www-form-urlencoded. If GET is selected as the Method, then only application/x-www-form-urlencoded is accepted as the Content Type.
Request Body (required)
The body to include in the request. This field supports Liquid templates.
VoxXML Redirect
- This widget allows the designer to redirect the flow to VoxXML. The URL that the flow is redirected to must contain valid VoxXML
Settings
Redirect URL (required)
The URL of a publicly available web application and can be a relative or absolute URL.
Request Method (required)
The HTTP method to use when sending the VoxXML Redirect request to the provided URL. The options are POST and GET.
Transitions
Returned
Activated when call control is returned back to the flow. Once the Redirect widget is executed, call control is given to the VoxXML served by the provided URL. To return control to the flow, the <Flow> noun must be used with the <Connect> verb.
Failed
Activated if the provided URL is invalid.
These are the widgets under the Control section in the VAST flow builder.
Conditions
- Conditions provide the flow with a mechanism to make logic decisions based on a selected variable, operation, and value.
Set Variables
- This widget sets a variable. Variables allow the designer to make flow decisions and can be used in Liquid templates. Once set, the variable will be accessible by name in other widgets.
Settings
Name of Variable (required)
The name of the variable.
Value (required)
The variable’s value. This field supports Liquid templates.
Unset Variables
- This widget deletes the specified variable(s). Once deleted, the variable will no longer be accessible to other widgets.
Settings
Variables (required)
The name(s) of the variable(s) to delete.
