Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Widget Library

This page documents all of the widgets available in the Studio drag and drop environment. New to Studio and want to learn about it? Jump to the Usage guide homepage!

Widget Library

Current Widgets:

💥 Trigger (Start)

Studio Trigger Widget

Description:

All Flows have a Trigger Widget: this is the Widget that begins the Flow. Other Widgets are attached to this Widget, connecting to one of the three possible trigger events: Incoming Call, Incoming Message, and REST API. This Widget cannot be deleted.

Required Configuration:

Flow Name is required, and defaults to the name entered when you create the Flow. You may modify this at any time.

The webhook URL of the flow (read-only), appears in the configuration panel, in this format:

https://webhooks.twilio.com/v1/Accounts/<account_sid>/Flows/<flow_sid>

You can copy the Flow URL to the clipboard in order to connect it to a Twilio number or make REST API requests.

Transitions: There are three initial events connected to the Trigger Widget: Incoming Call, Incoming Message, and REST API (Incoming Request). The Trigger Widget does not allow custom Transition events.

Variables:

Inbound Message Trigger

Account SID trigger.message.AccountSid
Body trigger.message.Body
From trigger.message.From
From City trigger.message.FromCity
From Country trigger.message.FromCountry
From State trigger.message.FromState
From ZIP trigger.message.FromZip
Message SID trigger.message.MessageSid
Messaging Service SID trigger.message.MessagingServiceSid
Number of Media Items trigger.message.NumMedia
To trigger.message.To
To City trigger.message.ToCity
To Country trigger.message.ToCountry
To State trigger.message.ToState
To ZIP trigger.message.ToZip

Inbound Call Trigger

Account SID trigger.call.AccountSid
API Version trigger.call.ApiVersion
Called trigger.call.Called
Caller trigger.call.Caller
Call Status trigger.call.CallStatus
Direction trigger.call.Direction
From trigger.call.From
From City trigger.call.FromCity
From Country trigger.call.FromCountry
From State trigger.call.FromState
From ZIP trigger.call.FromZip
Caller City trigger.call.CallerCity
Caller Country trigger.call.CallerCountry
Caller State trigger.call.CallerState
Caller ZIP trigger.call.CallerZip

Call SID

trigger.call.CallSid
Called City trigger.call.CalledCity
Called Country trigger.call.CalledCountry
Called State trigger.call.CalledState
Called ZIP trigger.call.CalledZip
To trigger.call.To
To City trigger.call.ToCity
To Country trigger.call.ToCountry
To State trigger.call.ToState
To ZIP trigger.call.ToZip

REST API Trigger

Variables passed in via REST API trigger will be available as Flow Data and accessible via {{flow.data.MY_CUSTOM_VARIABLE}} syntax. See the REST API page for more details.

⚙ Send & Wait For Reply

Send & Wait For Reply Widget

Description:

Send & Wait For Reply allows you to send an outgoing message, wait for a reply, and collect the user’s response. Use this Widget to collect replies to your messages, such as a YES to confirm an appointment or answering survey questions. You can also configure a timeout to wait for the response, after which we will assume "No Reply" and transition accordingly. You can use this to send a followup reminder message, trigger an outgoing voice call, or update your database with no response.

Required Configuration

Name

Description

Default

Message Body

The text of the message to send.

Send Message From

The “from” number -- choose one from Phone Number, MessagingServiceSid, OTT Id

Flow Default flow.channel.address

Stop Gathering After

The number of seconds to wait for a reply. Best practice is to limit the timeout to 4 hours or less. The entire Execution cannot live longer than 90 days due to our data retention policy.

3600 seconds

Optional Configuration

Name

Description

Default

Media URL

The URL of the media you wish you send out with the message (i.e. https://demo.twilio.com/owl.png)

Programmable Chat Service

Only applies for Flows working with Twilio Programmable Chat. A Chat service is where all the Channels, Messages, Users and other resources within a Chat deployment live. See the Chat Services REST API docs for more information.

trigger.message.InstanceSid

Programmable Chat Channel

Only applies for Flows working with Twilio Programmable Chat. Channels are the center of all chat activity within a Chat Service. Chat messages are sent to a particular channel. See the Chat Channels REST API docs for more information.

trigger.message.ChannelSid

Message Attributes

Only applies for Flows working with Twilio Programmable Chat. An optional string metadata field you can use to store any data you wish along with the sent message. The string value must contain structurally valid JSON if specified. See the Chat Mesages REST API docs for more information.

Using Programmable Chat:

Messages from a user in a Programmable Chat Channel can be received by Studio and responded to using the Send & Wait for Reply widget. To enable incoming Chat messages, add the Studio Flow's webhook URL as a Chat Channel webhook.

Example:

curl -X POST https://chat.twilio.com/v2/Services/ISxxxxxxxx/Channels/CHxxxxxxxxxx/Webhooks \
--data-urlencode "Type=studio" \
--data-urlencode "Configuration.FlowSid=FWxxxxxxxxx" \
-u ACCOUNT_SID:AUTH_TOKEN

New messages posted in the Chat Channel will create a new Studio Execution, enabling the Studio Flow to interact with the Chat user.

Variables:

The following variables will be added to the Execution context (where MY_WIDGET_NAME is the name of your actual widget):

outbound [The message Studio sent to the user]:

Sid

widgets.MY_WIDGET_NAME.outbound.Sid

To

widgets.MY_WIDGET_NAME.outbound.To

From

widgets.MY_WIDGET_NAME.outbound.From

Body

widgets.MY_WIDGET_NAME.outbound.Body

Status

widgets.MY_WIDGET_NAME.outbound.Status

ErrorCode

widgets.MY_WIDGET_NAME.outbound.ErrorCode

ErrorMessage

widgets.MY_WIDGET_NAME.outbound.ErrorMessage

inbound [The response message the user sent back to Studio]:

Sid

widgets.MY_WIDGET_NAME.inbound.Sid

To

widgets.MY_WIDGET_NAME.inbound.To

From

widgets.MY_WIDGET_NAME.inbound.From

Body

widgets.MY_WIDGET_NAME.inbound.Body

MediaUrl{N}

widgets.MY_WIDGET_NAME.inbound.MediaUrl0

If more than one media element is indicated by NumMedia than MediaUrl{N} will be used, where N is the zero-based index of the Media (e.g. MediaUrl0)



⚙ Split Based On...

Split Based On... Widget

Description:

Split Based On... allows you to split your Flow and connect to specific Widgets based on user conditions. Use this Widget to deal with conditions like a user replying “YES” to a SMS, or pressing “1” on their keypad while on a call.

Note: Studio conditions are not case-sensitive and automatically trim leading and trailing spaces of the values.

Required Configuration:

Name

Description

Example

Default

Variable To Test

The value (or expression) that is being tested.

For example, if you want to branch on message body, the Input would be the variable you stored the message in.

Select a predefined variable from the drop-down, or type a dynamic variable directly with curly braces: {{widgets.http_1.parsed.foo}}

{{widgets.send_message_1.message.Body}}

N/A



Transitions:

You’ll define the event(s) that trigger transitions from this Widget. You get No Match for free once you set a branch.

Name

Description

Default

Condition Matches

Example: “YES” for when text matches “YES”

NEW TRANSITION

No Match

Input does not match any of the user-defined conditions

NO MATCH

Conditions take the form: subject predicate [value] and can be set in the right-side panel.

subject: the configuration parameter defined as Input.

predicate: the operator to use -- equals, greater than, etc.

[value]: the value you are comparing against. Constants, variables, and expressions are supported. Value can be null for certain conditions, such as “is blank” or “has any value”

In the following example, we have asked the user if they would like to receive reminders. Following the Send & Wait For Reply Widget is a Split Based On... Widget that evaluates the user’s response.

We have three conditions:

  1. The user enters Y (YES) when prompted
  2. The user enters N (NO) when prompted
  3. The user enters another value (NO MATCH)

Subject

Predicate

Value

{{widgets.reminders_response.inbound.Body}}

Equals

Y

{{widgets.reminders_response.inbound.Body}}

Equals

N

The YES condition Transitions to a Send SMS Widget called REMINDERS_CONFIRM, while the NO and NO MATCH conditions Transition to a Send SMS Widget called REMINDERS_OPTOUT

Here are some usage examples of other conditions:

Subject

Predicate

Value

{{flow.data.appointment_date}}

Is After Date

2017-09-04

{{flow.data.appointment_time}}

Is Before Time 16:35

{{flow.data.reward_points}}

Greater Than

1000

{{flow.data.first_name}}

Is Blank

{{trigger.message.Body}}

Matches Any Of yes,yeah,yup

{{flow.data.survey_result}}

Regex

[1-5]

Note: Omit leading and trailing slashes. Matching is case-insensitive.



⚙ Send Message

Send Message Widget

Description:

Send Message allows you to send a message to a user. Use this Widget to send messages to the user before any other action. If you want to request a user’s input after a message, use the Send & Wait For Reply Widget instead.

Required Configuration

Name

Description

Default

Message Body

The text of the message to send.

Send Message From

The “from” number -- choose one from Phone Number, MessagingServiceSid, OTT Id

Flow Default flow.channel.address

Send Message To

The "to" number, or recipient of the message

Flow Default contact.channel.address

Optional Configuration

Name

Description

Default

Media URL

The URL of the media you wish you send out with the message (i.e. https://demo.twilio.com/owl.png)

Programmable Chat Service

Only applies for Flows working with Twilio Programmable Chat. A Chat service is where all the Channels, Messages, Users and other resources within a Chat deployment live. See the Chat Services REST API docs for more information.

trigger.message.InstanceSid

Programmable Chat Channel

Only applies for Flows working with Twilio Programmable Chat. Channels are the center of all chat activity within a Chat Service. Chat messages are sent to a particular channel. See the Chat Channels REST API docs for more information.

trigger.message.ChannelSid

Message Attributes

Only applies for Flows working with Twilio Programmable Chat. An optional string metadata field you can use to store any data you wish along with the sent message. The string value must contain structurally valid JSON if specified. See the Chat Mesages REST API docs for more information.

Using Programmable Chat:

Messages from a user in a Programmable Chat Channel can be received by Studio and responded to using the Send Message widget. To enable incoming Chat messages, add the Studio Flow's webhook URL as a Chat Channel webhook.

Example:

curl -X POST https://chat.twilio.com/v2/Services/ISxxxxxxxx/Channels/CHxxxxxxxxxx/Webhooks \
--data-urlencode "Type=studio" \
--data-urlencode "Configuration.FlowSid=FWxxxxxxxxx" \
-u ACCOUNT_SID:AUTH_TOKEN

New messages posted in the Chat Channel will create a new Studio Execution, enabling the Studio Flow to interact with the Chat user.

Variables:

Outbound

SID widgets.MY_WIDGET_NAME.outbound.Sid
To widgets.MY_WIDGET_NAME.outbound.To
From widgets.MY_WIDGET_NAME.outbound.From
Body widgets.MY_WIDGET_NAME.outbound.Body
Status widgets.MY_WIDGET_NAME.outbound.Status

⚙ Say/Play

Say / Play Widget

Description:

Say/Play allows you to play a recorded message or dictate text to a user on call. Use this Widget to say or play information to the user before any subsequent action. If you want to request a user’s input after a message, use the Gather Widget instead.

Conditional Configuration

One of the following is required:

Name

Description

Default

Say or Play Message

A choice indicating whether to play a pre-recorded message or say text.

Say

Optional Configuration

Name

Description

Default

Text To Say

(if Say) The text to say. Templates are supported so you can say things like “Hello {{first_name}}

Tip: Adding periods with spaces in between will insert a pause in the speech: “Hello . . . {{first_name}}”. Roughly 15 spaced-out periods equals one second of silence.

Message Voice

(if Say) Select the voice of your choosing from a dropdown.

alice

URL of Audio File

(if Play) The URL of of media to play, i.e. https://api.twilio.com/cowbell.mp3.

Supported MIME Types: <Play>

Language

(if Say) Select the language of your choosing from a dropdown.

en

Number of Loops

Choose how many times you would like the message to loop.

1




⚙ Gather Input On Call

Gather input on call widget

Description:

Gather Input On Call allows you to gather a user’s input while they are on call. Use this Widget to collect DTMF information. This can then be saved (great for collecting data) or sent to another Widget (such as a Split Based On... Widget) to send the user down the right path.

There is no required configuration for the Gather Widget.

Optional Configuration

Name

Description

Supported Values

Default

Say or Play a Message

A choice indicating whether to play a pre-recorded message or say text (just as with Say/Play).

Say a Message, Play a Message

Say a Message

Text To Say

(if Say) The text to say. Templates are supported so you can say things like “Hello {{first_name}}”

Language

(if Say) Language and regional dialect for the message being said.

See dropdown list on the widget

en

Message Voice

(if Say) Select the voice of your choosing from a dropdown.

Varies based on language selected

alice

URL of Audio File

(if Play) The URL of of media to play, i.e. https://api.twilio.com/cowbell.mp3.

Number of Loops

Choose how many times you would like the message to loop.

1

Stop Gathering After ___ Seconds

Time to wait for the caller to press a key.

1s - 30s

5s

Speech Recognition Language

Language the speech engine will try to recognize.

See complete list en-US

Speech Recognition Hints

A list of comma-separated hint values.

Stop Gathering On Keypress?

If Twilio should listen for a specific keypress to stop gathering digits. If set to "No," all keypresses will be gathered and submited once the the Stop Gathering After timeout is reached or the expected Number of Digits are collected.

Yes/No

Yes

Stop Gathering On Keypress ___

A value that will submit the received data as soon as it’s pressed. Note: This is a control key and its value is not submitted with the rest of the gathered digits.

0-9,#,* or blank

#

Stop Gathering After Number Of Digits

The number of digits you are expecting and will submit as soon as that number is reached.

0-9, or blank



Variables:

Account SID widgets.MY_WIDGET_NAME.AccountSid
API Version widgets.MY_WIDGET_NAME.ApiVersion
Called widgets.MY_WIDGET_NAME.Called
Caller widgets.MY_WIDGET_NAME.Caller
Call Status widgets.MY_WIDGET_NAME.CallStatus
Direction widgets.MY_WIDGET_NAME.Direction
From widgets.MY_WIDGET_NAME.From
From City widgets.MY_WIDGET_NAME.FromCity
From Country widgets.MY_WIDGET_NAME.FromCountry
From State widgets.MY_WIDGET_NAME.FromState
From ZIP widgets.MY_WIDGET_NAME.FromZip
Caller City widgets.MY_WIDGET_NAME.CallerCity
Caller Country widgets.MY_WIDGET_NAME.CallerCountry
Caller State widgets.MY_WIDGET_NAME.CallerState
Caller ZIP widgets.MY_WIDGET_NAME.CallerZip
Call SID widgets.MY_WIDGET_NAME.CallSid
Called City widgets.MY_WIDGET_NAME.CalledCity
Called Country widgets.MY_WIDGET_NAME.CalledCountry
Called State widgets.MY_WIDGET_NAME.CalledState
Called ZIP widgets.MY_WIDGET_NAME.CalledZip
To widgets.MY_WIDGET_NAME.To
To City widgets.MY_WIDGET_NAME.ToCity
To Country widgets.MY_WIDGET_NAME.ToCountry
To State widgets.MY_WIDGET_NAME.ToState
To ZIP widgets.MY_WIDGET_NAME.ToZip
Confidence widgets.MY_WIDGET_NAME.Confidence
Digits widgets.MY_WIDGET_NAME.Digits
Speech Result widgets.MY_WIDGET_NAME.SpeechResult
Unstable Speech Result widgets.MY_WIDGET_NAME.UnstableSpeechResult

⚙ Run Function

Run function widget

Description:

Run Function allows you to execute Twilio Functions (lightweight, serverless pieces of code that run in the Twilio cloud) within your Flow. Use this Widget to write business logic that works alongside Studio Widgets to fully realize your application.

When you invoke a Function, you have two possible options for using variables: (1) you can pass Flow variables as parameters into a Function (e.g. flow.data.foo), and (2) you may set Flow variables with data returned from the Function (TwiML or JSON can be returned).

Note: For unique use cases, the Run Function widget can return custom TwiML to enhance your Studio Flow.

Required Configuration

The only required configuration for a Function Widget is the URL of the Function you would like to call. You may select it from a dropdown or search for the Function by name.

Name

Description

Example

Default

Function URL

The Function you’d like to invoke.

Hello SMS

None

Optional Configuration

There are several optional configurations for the Function Widget:

Name

Description

Default

Function Parameters

Zero or more extra parameters that will be passed to the Function expressed as key/value pairs. String literals and variables are supported.

None

Transitions:

This Widget has two events that trigger transitions.

Name

Description

Success

A successful return (HTTP 20X)

Fail

The Function does not successfully return (or has an error)

Response:

The HTTP response from the Function must return a 2xx status code within 5 seconds, and the response body must not exceed 64kB.

Response Recommendation Notes
Status Code 200 or 204 3xx redirection is supported. 4xx or 5xx status code will transition to "failed" in the widget.
Content Type application/json Content-Type header is not required if Status Code is 204 No Content. Other content types are supported, such as plain text or XML. But only application/json objects (e.g. {"foo":"bar"}) will be automatically parsed into Studio variables.
Body valid JSON Body content must match the Content-Type header.
Response Time 5 seconds or less Studio will timeout the request at 5 seconds and transition to "failed" in the widget.
Response Size Maximum 64kb Studio can only process responses up to 64kB.


Variables:

Twiml: If your function returns Twiml, the twiml will be returned to the calling client.

Json: If your function returns valid Json, you should be able to access it via widgets.MY_WIDGET_NAME.parsed

For example, if you return {"message": "Hi", "person": {"name": "Bob", "age": 40}}, you can reference that in subsequent widgets as:

widgets.MY_WIDGET_NAME.parsed.message

widgets.MY_WIDGET_NAME.parsed.person.name

widgets.MY_WIDGET_NAME.parsed.person.age

For all return types, you will have the following variables:

widgets.MY_WIDGET_NAME.body

widgets.MY_WIDGET_NAME.status_code

widgets.MY_WIDGET_NAME.content_type

⚙ Make Outgoing Call

Make outgoing call widget

Description:

Make Outgoing Call allows you to dial the Contact's phone number within your Flow. Use this Widget to reach the Contact with an automated call, and follow up by adding voice messages.

Required Configuration:

The required fields for this Widget are To and From. The To must be the Contact's phone number and cannot be changed, but the From can be variables or hard-coded phone numbers.

Name

Description

Default

Number To Call

The Contact's phone number (cannot be changed)

Flow Default contact.channel.address

Number to Make Call From

The phone number to use as the Caller ID

Flow Default flow.channel.address

Optional Configuration:

Name

Description

Default

Record

Record the call and save as an mp3

Values: true, false

false

⚙ Connect Call To

Connect Call To Widget

Description:

Connect Call To allows you to bridge an in-progress call with another phone number (or numbers), Client user, SIM, SIP endpoint, or conference. Use this widget to connect your customer with a different department, or if they’re looking to reach a specific operator.

Required Configuration:

The required fields for this Widget are Connect Call To and Caller ID, which can be variables or hard-coded entries. Select the Connect Call To type from the dropdown in the Inspector Panel, then set the field value to the number(s)/address that most accurately reflects the intended recipient.

Name

Description

Default

Connect Call To

The phone number(s), Client user, SIM, SIP endpoint, or conference to call.
Note: For Multiple Numbers, separate each with commas: +14157234000, +14155551212, +14158675310

Caller ID

The phone number to use as the Caller ID

Flow Default contact.channel.address

Optional Configuration:

Name

Description

Default

Record

Record the call and save as an mp3

Values: true, false

false



⚙ HTTP Request

HTTP Request widget

Description:

HTTP Request allows you to interact with applications and code that live outside Studio. Use this widget to interact with parts of your business logic not defined in flows or as Functions.

Note: Returning custom TwiML from an HTTP Request widget isn't supported. Use the Run Function widget instead, and follow our guide for returning custom TwiML from Twilio Functions.

Required Configuration:

The required fields for this Widget are Request Method and Request URL. The Request Method can be selected from a dropdown, and the URL is able to be set as Automatic.

Name

Description

Request Method

The desired HTTP method of your request (GET or POST)

Request URL

The URL you would like to make a request to.

Tip: For secure URLs, add your Basic Authentication credentials. Example: https://user:password@mydomain.com/handler.php

Content Type Content type of the request body, either application/x-www-form-urlencoded or application/json.

Optional Configuration:

You may optionally decide to declare a request body and HTTP parameters for this Widget.

Name

Description

Request Body

Text to include as the body of your request.

HTTP Parameters

Key-value pairs of parameters to pass along with the request. String literals and variables are supported.


Transitions:

This Widget has two events that trigger transitions.

Name

Description

Success

A successful return (HTTP 20X)

Fail

The URL does not successfully return (or has an error)

Response:

The HTTP response from the URL must return a 2xx status code within 5 seconds, and the response body must not exceed 64kB.

Response Recommendation Notes
Status Code 200 or 204 3xx redirection is supported. 4xx or 5xx status code will transition to "failed" in the widget.
Content Type application/json Content-Type header is not required if Status Code is 204 No Content. Other content types are supported, such as plain text or XML. But only application/json objects (e.g. {"foo":"bar"}) will be automatically parsed into Studio variables.
Body valid JSON Body content must match the Content-Type header.
Response Time 5 seconds or less Studio will timeout the request at 5 seconds and transition to "failed" in the widget.
Response Size Maximum 64kb Studio can only process responses up to 64kB.


Variables:

Json: If your function returns valid Json, you should be able to access it via widgets.MY_WIDGET_NAME.parsed

For example, if you return {"message": "Hi", "person": {"name": "Bob", "age": 40}}, you can reference that in subsequent widgets as:

widgets.MY_WIDGET_NAME.parsed.message

widgets.MY_WIDGET_NAME.parsed.person.name

widgets.MY_WIDGET_NAME.parsed.person.age

For all return types, you will have the following variables:

widgets.MY_WIDGET_NAME.body

widgets.MY_WIDGET_NAME.status_code

widgets.MY_WIDGET_NAME.content_type

⚙ Record Voicemail

Record VM widget

Description:

Record Voicemail allows you to record the audio of a call and optionally transcribe it. Use this widget to save your conversation with customers. You can play back the audio file by referencing its URL in a Play widget using widgets.MY_WIDGET_NAME.RecordingUrl.

Note that Studio does not handle transcription processing automatically. You can specify the callback URL when transcription is complete and handle it yourself. Using a Function is a great way to customize the behavior, such as emailing the transcription, although it requires writing some code.

Variables:

SID widgets.MY_WIDGET_NAME.Sid
Date Created widgets.MY_WIDGET_NAME.DateCreated
Date Updated widgets.MY_WIDGET_NAME.DateUpdated
Account SID widgets.MY_WIDGET_NAME.AccountSid
Call SID widgets.MY_WIDGET_NAME.CallSid
RecordingUrl widgets.MY_WIDGET_NAME.RecordingUrl
Duration widgets.MY_WIDGET_NAME.Duration
Price widgets.MY_WIDGET_NAME.Price
Price Unit widgets.MY_WIDGET_NAME.PriceUnit
API Version widgets.MY_WIDGET_NAME.ApiVersion
URI widgets.MY_WIDGET_NAME.Uri
Status widgets.MY_WIDGET_NAME.Status
Source widgets.MY_WIDGET_NAME.Source
Channels widgets.MY_WIDGET_NAME.Channels

⚙ Enqueue Call

Enqueue Call Widget

Description:

Enqueue Call enqueues the current call into a call queue. The caller will hear hold music until the call is dequeued by another caller.

Required Configuration:

You must select a Queue or TaskRouter Task when configuring this Widget. The choice may be selected from a dropdown, with additional configuration fields appearing based on the selection.

Name

Description

Queue Name

The name of the Queue to place the call into (i.e. "Everyone"). If this Queue doesn’t exist, it will be created on demand. Max length of 64 characters.

Workflow SID

The desired Workflow ID for handling the TaskRouter Task.

Optional Configuration:

You may optionally decide to declare task attributes, priority, timeout, and a hold music TwiML URL for the request initiated by this Widget.

Name

Description

Task Attributes

JSON representing task attributes (max 1024 characters)

Priority

The priority of this task in the TaskQueue. Tasks with a higher priority are assigned before older tasks with a lower priority. If not specified, will be treated as 0 during evaluation.

Timeout

The number of seconds you want the task to remain in this TaskQueue. Must be a positive integer < 2 weeks in seconds. If not specified, defaults to infinity.

Hold Music TwiML URL

The URL for custom hold music TwiML. If not specified, the default hold music will play upon enqueue.

Transitions:

Name

Description

Call Complete

Transition is triggered when the Enqueue action URL is requested. Due to the underlying behavior of the Enqueue action URL, Studio can only regain control of the live call after dequeueing if the call was originally dequeued using <Dial><Queue>.

Failed to Enqueue

Transition is triggered if enqueuing of the call fails, such as if the queue is full (max 100 members).

Call Failed

Transition is triggered if QueueResult is "system-error".

⚙ Autopilot

Autopilot Studio Wdiget

Description:

Send calls or messages to Autopilot's intelligent assistant platform. Autopilot allows you to build conversational IVRs and chatbots using natural language understanding and conversational flows for voice calls, SMS, and messaging apps like Whatsapp, Google Assistant, and FB Messenger.

Required Configuration:

You must select an Autopilot Assistant when configuring this Widget.

Name

Description

Assistant Unique Name

The Autopilot's Assistant unique name

Messaging and Chat Configuration:

You need to specify the following configuration when using the Autopilot widget with SMS Messaging or Chat.

Name

Description

Default

Send Message From


The Bot's name that the end user sees on the Chat.

Programmable Chat Service

The Programmable Chat Service Sid where the chat is deployed.

{{trigger.message.InstanceSid}}

Message Attributes

The Programmable Chat Channel where the messages are sent and where the bot should reply.

{{trigger.message.ChannelSid}}

Body

The message to be sent to Autopilot for natural language understanding.

{{trigger.Message.Body}}

Transitions:

Name

Description

Session Ended

When Autopilot Session ends either by doing a handoff or the absence of a listen.

Error


When a system error occurs

⚙ Send to Flex

Send to Flex widget

Description:

For Flex-enabled Projects, Send to Flex transfers a call or a message to Flex by creating a TaskRouter Task. Voice calls are enqueued and the caller will hear hold music while waiting for a Worker. Messages are transferred to Flex as new tasks for assignment to a Worker.

Required Configuration:

You must select a Workflow and Channel when configuring this Widget.

Name

Description

Workflow

The name of the Flex Worfklow assigned to the Project.

Channel

The Task Channel being used. Only Voice and Chat are currently supported (select Chat for SMS).

Optional Configuration:

You may optionally decide to declare task attributes, priority, timeout, and a hold music TwiML URL for the request initiated by this Widget. These

Name

Description

Priority

The priority of this task in the TaskQueue. Tasks with a higher priority are assigned before older tasks with a lower priority. If not specified, will be treated as 0 during evaluation.

Timeout

The amount of time in seconds the task is allowed to live up to a maximum of 2 weeks. Defaults to 24 hours if not supplied.

Attributes

JSON representing task attributes (max 1024 characters)

URL Method

Method to be used when requesting the Hold Music TwiML URL (GET or POST)

Hold Music TwiML URL

The URL for custom hold music TwiML. If not specified, the default hold music will play upon transfer.

Transitions:

Name

Description

Task Created

For Voice calls, transition is triggered when the Enqueue action URL is requested. For Messages, transition is triggered as soon as the TaskRouter Task is created.

Failed to Create Task

For Voice calls, transition is triggered if enqueuing of the call fails. For Messages, transition is triggered immediately when TaskRouter returns an error for Task creation.

Call Failed

Only applies to Voice calls. Transition is triggered if QueueResult is "system-error".

⚙ Capture Payments

Capture Payments widget

Description:

Capture Payments allows you to securely capture credit card details on a call and either tokenize or process the payment using a Payment Gateway. This widget uses the underlying TwiML verb <Pay>.

Note: Use of Capture Payments requires PCI Mode to be enabled in Voice Settings.

Optional Configuration:

Name

Description

Timeout

Sets the limit in seconds to wait for the caller to press another digit before moving on to validate the digits captured.

Max Attempts

Number of times to retry when collecting information.

Language

Language to speak when prompting the caller for credit card details.

Valid Card Types

Credit card types that should be accepted. Allows multiple values.

Request Security Code

Whether to prompt for credit card security code.

Request Postal Code

Whether to prompt for postal code.

Pay Connector

Unique Name corresponding to the Payment Gateway Connector installed in Twilio Add-ons

Payment Token Type

Select one-time payment or reusable payment.

Charge Card with Amount

Amount to be charged.

Currency

Currency to use when charging the card.

Description

Description of the payment.

Transitions:

Name

Description

Success

Payment has completed successfully.

Max Failed Attempts

Maximum number of failed attempts has been reached.

Provider Error

Error communicating with Payment Provider.

Pay Interrupted

Payment process interrupted by caller pressing *.

Hang Up

Caller hung up during payment process.

Validation Error

Invalid attributes received.

⚙ Set Variables

Set Variables Widget

Description:

Set Variables allows you to save key/value pairs in the global context of the flow execution. Variables set via the widget are accessible throughout your flow via other widgets under the key {{flow.variables.<key>}}. This allows you to enable use cases such as counters that are dynamically updated as your flow executes.

Optional Configuration:

You can add any number of Variables. Variables can have static values like a single number or string, or dynamic values set via the Liquid templating language.

Example that sets a variable called count to 0 if not set and increments it if it exists:

{% if flow.variables.count %}
  {{flow.variables.count | plus: 1}}
{% else %}
  0
{% endif %}

Configuration

Name

Description

Key

The name of this variable, once set, will be accessible in liquid via {{flow.variables.<key>}}.

Note: Variable names are case sensitive. Foo is a different variable to foo.

Value

The variable value to set. This can be a number or string value, or a liquid template block like the example above.

Transitions

There is only one transition from this widget, "Next" which fires once any variables specified are set.

Example Flow

In the call flow screenshot below, the count variable is set to 0 when the flow starts, and the flow will loop until the count variable is equal to 3 and then exit (The set variable widget uses the sample liquid template code from above).

Screen Shot 2018-12-11 at 10.11.23 AM.png

⚙ Fork Stream

Fork Stream Studio Widget

Description:

Fork Stream allows you to send real-time audio streams of a phone call over the Internet. Websocket and SIPREC protocols are supported.

Required Configuration:

You must select an Action when configuring this Widget.

Name

Description

Action

Whether you want to Start or Stop a stream.

Optional Configuration:

Name

Description

Stream Name

Friendly name given to the Stream

Stream Type

Transport protocol, one of WebSocket or SIPREC.

URL

URL of the service where to stream the audio. This is requrired when the Stream Type is WebSocket. The only supported protocol is wss.

Connector Name

Name of the Add-on use to configure the Stream. This is required when Stream Type is SIPREC.

Tracks

Select audio streams to be sent. Can be any of: Inbound Track, Outbound Track or Both Tracks

Stream Parameters

Zero or more extra parameters expressed as key/value pairs that will be sent to the remote service during connection.

Transitions

The "Next" transition fires inmediately after the Stream connection has been created (Start) or terminated (Stop).

Example Flow

In the call flow screenshot below the audio streams of an incoming call are forked for real-time processing while the call is bridged to another phone number.

Fork Stream Studio Flow

⚙ Call Recording

Call Recording

Description:

Call Recording allows you to switch Voice Call Recording ON or OFF at any point during a call flow.

Warning!

The Call recording widget cannot be placed as the first widget - it must come after another widget like an initial Say/Play or Gather. It is important to consider whether your use case requires that your customers be warned before a call is recorded.

Required Configuration:

You must choose whether the Recording is to be switched on or off.

Name

Description

Default

RECORD CALL

A toggle button (boolean) to allow users to Toggle Call Recording to On or Off within a Call Flow

  1. Start Recording
  2. Stop Recording

Please note that these options are not for pausing and resuming a Voice Recording, they are specifcally meant for Start and Stop.

Please do read Legal Considerations with Recording Voice and Video Communications

False

Optional Configuration:

You may optionally decide to declare recording Status Call back Url, Recording Channels, trim behaviour and a for the request initiated by this Widget.

Name/Key

Description

Default

RECORDING STATUS CALLBACK URL

The URL we should call using the recording_status_callback_method on each recording event specified inrecording_status_callback_event. For more information, see RecordingStatusCallback parameters.

empty

RECORDING STATUS CALLBACK METHOD

The HTTP method we should use to call recording_status_callback. Can be: GET or POST. The default is POST.

POST

RECORDING STATUS EVENT

The recording status events on which we should call the recording_status_callback URL. Can be: in-progress, completed and absent. Default is completed. Separate multiple event values with space.

completed

RECORDING CHANNELS

The number of channels used in the recording. Can be: mono or dual and the default is dual. mono records all parties of the call into one channel. dual records each party of a 2-party call into separate channels.

TRIM

Whether to trim any leading and trailing silence in the recording. Can be: trim-silence or do-not-trim and the default is do-not-trim. trim-silence trims the silence from the beginning and end of the recording and do-not-trim does not.

do-not-trim



Transitions:

These are the events that trigger transitions from this widget:

Name

Key

Description

Success

success

The call recording was successfully toggled

Failed

failed

Could not toggle call recording

Variables:

The following variables will be added to the Execution context (where MY_WIDGET_NAMEis the name of your actual widget):

Status

widgets.MY_WIDGET_NAME.status

Conference SID

widgets.MY_WIDGET_NAME.conference_sid

Price Unit

widgets.MY_WIDGET_NAME.price_unit

Date Updated

widgets.MY_WIDGET_NAME.date_updated

Start Time

widgets.MY_WIDGET_NAME.start_time

Recording Uri

widgets.MY_WIDGET_NAME.uri

Account SID

widgets.MY_WIDGET_NAME.account_sid

Channels

widgets.MY_WIDGET_NAME.channels

Source of Recoring Start

widgets.MY_WIDGET_NAME.source

Encryption Details

widgets.MY_WIDGET_NAME.encryption_details

Call SID

widgets.MY_WIDGET_NAME.call_sid

Recording SID

widgets.MY_WIDGET_NAME.sid

Duration

widgets.MY_WIDGET_NAME.duration

Date Created

widgets.MY_WIDGET_NAME.date_created

Error Code

widgets.MY_WIDGET_NAME.error_code

Price

widgets.MY_WIDGET_NAME.price

API Version

widgets.MY_WIDGET_NAME.api_version

⚙ TwiML Redirect

TwiML Redirect Widget.png

Description:

TwiML Redirect allows you to redirect a call or message to be handled outside of Studio.

Returning control to Studio

To handle returning control to Studio, you need to specify a <Redirect> to the Studio Webhook URL and append ?FlowEvent=return. Any additional parameters specified in the return URL will be injected into the Studio context and addressable via Liquid template variables.

Example:

<Response>
  <Say>Returning you back to the Studio Flow.</Say>
  <Redirect>https://webhooks.twilio.com/v1/...?FlowEvent=return&foo=bar</Redirect>
</Response>

The URL parameter foo illustrated above will be passed automatically into your Flow and can be referenced via Liquid as {{widgets.your_redirect_widget_name.foo}}.

Tip: To retrieve the Studio Webhook URL, in your Studio flow, click the red Trigger widget. The URL starting with https://webhooks.twilio.com/v1/... is the Webhook URL.

Required Configuration:

Name

Description

Default

URL

URL where the call or message will be redirected.

None

Optional Configuration:

Name

Description

Default

Method

HTTP method to be used in the redirect

POST

Timeout

Number of seconds to wait for control to be returned to Studio. Set to 0 if returning control is not desired.

Possible values in seconds: 0 to 14400 seconds (4 hours)

14400

Transitions:

These are the events that trigger transitions from this widget:

Name

Key

Description

Return

return

Fired when the next TwiML fetch is received from Voice or Messaging for the current Execution

Timeout

timeout

Fired when the timer is expired, and no new TwiML fetch is received for the current Execution

Failed

failed

Fired when the URL is not successfully returned (or has an error)

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.