Twilio Studio

Overview

What is Twilio Studio?

Twilio Studio is a visual interface to design, deploy, and scale customer communications. Twilio Studio, a new addition to the Twilio Engagement Cloud, is the first visual interface that empowers millions of cross-functional team members to design, deploy, and scale customer communications. Companies can now fast-track their customer engagement roadmap using the creative talent of the entire organization.

When to use Twilio Studio?

Anyone on your team can use Twilio Studio to quickly and easily create and modify flows. Studio is designed for use by cross-functional teams, and it provides a common framework for everyone to do the work they need to do. Designers can make swift UX modifications, copywriters can implement their own changes to messaging, and developers can delegate work to others and focus on building more complex features (such as calling Functions).

Studio Features

  • Trigger Flows via Inbound SMS, Inbound Voice Calls, and Webhooks
  • Create, Modify, and Destroy Flows (Workflows)
  • Add and Remove Transitions
  • Manage Widget Settings with the Inspector Panel
  • Define Transitions to Advance Users through Flows
  • Create and Pass Variables
  • View Engagements (Individual runs through flows)
  • Organize Use Cases and Logic in Separate Flows

Getting Started

Request early access to Studio here.

Usage

Glossary

Here are a few of the key terms that will help you as you get started with Studio:

Term

Definition

Example

Flow

Flows are individual workflows that you create. They can handle one or more use cases.

You can create a Flow to handle inbound Voice calls by playing a prerecorded message.

Widget

Widgets are individual items that can be dragged onto the Flow canvas. They represent pieces of logic, and can connect to each other via Transitions.

The Send Message widget can be used to send an outbound SMS to a user who is in your Flow.

Transition

Transitions define how a Flow advances from one Widget to the next based on specified conditions.

You might have a Transition based on the condition of an incoming message; you could handle specific text inputs and route them to a Split Based On… Widget.

Step

A Step is the runtime processing of a Widget, starting when that Widget is entered. Variables get set at the end of a Step.

If you’re prompting a user for a text input, when they receive the inbound SMS prompt, they are actively in a Step until they exit the Widget (send a response or timeout). If the prompt is intended to set a variable, this happens at the end.

Engagement

An Engagement represents a specific person’s run through a Flow. An engagement is active while the user is in the Flow, and it is considered ended when they stop or are kicked out of the Flow.

When I call the Twilio number connected to a Flow, an Engagement is created to represent my call to that number / path through the Flow. The owner of the Flow can see my Engagement, as well as the Engagements of other users who have run through the Flow.

 

Creating Flows

Flows can be created in the console by clicking +

create a new Studio Flow by clicking on the +

You can have many flows, which can represent different use cases or as a way to organize logic.

Using Studio

The canvas is where you’ll build your Flows. It begins with the Trigger widget, and from there, you can drag and drop Widgets to build the exact Flow to meet your use case.

a fresh Studio canvas

 

The Widget Library panel can be found on the right side of the Flow canvas, and includes several drag-and-drop-ready Widgets. When you select a Widget, this panel transforms into the Inspector Panel.

Simply drag any of these Widgets onto the canvas, and connect it to your new or existing Flow. You’ll see configuration options in the same right-side panel when you click on an individual Widget.

 

say/play widget


Widgets are the building blocks of the Flow. They allow you to handle incoming actions and respond accordingly, sending a message, routing the user to another part of the Flow, capturing information, and more.

You can configure Widgets via the Inspector Panel (in the same right panel as the Widget Library). Simply click on a Widget to show configuration options. You may give Widgets custom names; the type will always show in parentheses so you can always tell what a widget does. Note that widget names must be unique, must start with a letter and cannot include spaces or periods -- use the underscore character to separate words.

Some Widgets have required configuration settings -- these will be indicated with a red asterisk and in the Widget Library reference below. You won’t be allowed to save your Flow if any required configurations are missing or invalid.

The canvas can sometimes get crowded (especially in complex Flows!) so it’s important to be able to control the area of focus. You can use the mouse to drag and reposition the canvas, and you can use the Zoom in / out links to change zoom. You can also pinch and squeeze to zoom if you are using a trackpad.

Defining Transitions

A Transition defines how a flow advances from one widget to the next based on events and specified conditions. From the canvas, you can simply tap New from a Widget to call up Transition options.

transitions

You can also set Transitions in the right-side Inspector Panel by clicking on New Transition. Transitions are often pre-set based on the type of Widget, and usually reflect the state of a call or message -- Was a response received? Did the call time out? Did the message send successfully?

Each Transition connects to another Widget. You may choose to set different destination Widgets for each Transition, or have two or more Transitions point to the same Widget (for example, if you want a user saying the number “one” to map to the same Widget as that user pressing the 1 key on the keypad). 

To remove a Transition, click on the widget that starts the Transition and drag the line away. You can also click on the widget, select the Transitions tab on the configuration pane and click on the "..." next to the transition you would like to remove, then click on the Disconnect Transition option from the dropdown menu.

Triggering Flows

There are three ways to trigger a Flow’s start:

  • Incoming message
  • Incoming phone call
  • REST API (Inbound request)

All three of these appear in the Trigger Widget, and you can drag-and-drop from one of more to reflect the needs of your use case.

flow-url

 

Once you’re happy with your Flow, you can connect it to a Twilio Number so people can start interacting with it! Simply navigate to the Console > Phone Numbers > Manage Numbers, choose the number you’d like to connect to the Flow, and select Studio Flow for when a call comes in (for Voice) and when a message comes in (for SMS). Choose your Flow from the dropdown, and save to connect.

studio-to-phone-number

 
Try calling the number in the screenshot -- if you hear a message referencing this guide, it’s powered by a Flow!

You can also copy-paste the Webhook URL onto any Twilio resource that takes a callback URL, including phone numbers, short codes, and Channels. Depending on the product, this can be done in the Console, via API, or both.

Note: that triggering outbound flows requires hitting the REST API, not the webhook URL. See the Studio REST API docs below for more details.

Working With Variables

As your flow executes, we save the state in what's called the Flow Context. Any data in the flow context can be accessed by your widgets as variables, either in configuration fields or in text areas as variable substitution. 

Studio supports the Liquid template language. which supports both output tags and logic tags. For example, to send a text message and include the contact's name, you could use variables like so:

Hello {{flow.data.first_name}}

More sophisticated logic is also supported. In this example, assume you want to check if you actually know the contact's name before trying to reference it:

{% if flow.data.first_name %}

Hello {{flow.data.first_name}}

{% else %}

Hello friend

{% endif %}

Context Variables

There are 4 types of data stored in the Context:

  • Flow: data intrinsic to the flow, such as the phone number associated with it
  • Trigger: data that gets set when a flow is initiated, such as the initial incoming message, phone call, or REST API.
  • Widgets: data that each widget sets itself and adds to the context as it gets executed, such as the digits a user presses or the body of an incoming message.
  • Contact: data about the current contact engaging with your flow, such as their phone number

Flow Variables include:

The flow's address (e.g. Twilio phone number):      flow.channel.address

Contact Variables include:

The user's address (e.g. handset phone number):    contact.channel.address

After execution, many widgets publish data variables to the Engagement context, and these variables may be referenced by subsequent widgets.  For example, when the Send Message widget step completes, it will have stored the following variables:

Sid             widgets.MY_WIDGET_NAME.message.Sid

To              widgets.MY_WIDGET_NAME.message.To

From              widgets.MY_WIDGET_NAME.message.From

Body              widgets.MY_WIDGET_NAME.message.Body

Note the casing of variable names, and remember that widget names must be unique, must start with a letter and cannot include spaces or additional periods.  Any variables that come from an external source, such as a status callback or Twilio API call, are cased according to the relevant spec for that callback. For example, an incoming message will have a "Body" parameter, where we keep the capitalized "Body" like in the Twilio SMS API. Variables specific to the flow, trigger, and widgets context are lower cased.

If a Flow is triggered via an inbound request (REST API), variables can be passed in at request time.

Publishing Flows & Revision History

When using the basic version of Studio, whenever a flow is changed and valid, it is automatically live for consumers to engage with. If your flow has validation errors, consumers will continue interacting with the most recent valid flow.

For more fine grained control over editing and publishing flows, you need to upgrade to Studio Plus. With Draft/Publish enabled, changes are automatically saved but will not be made live for consumers until you explicitly click "Publish". This lets you safely make changes and when you're happy with the final product, publish them for everyone.

Studio Publish Button

Studio Plus also includes Revision History. You will be able to see a lof every change made to your flow and the differences between the currently published version and the latest draft. 

Studio Revision History Popup

 Testing draft flows is easy with Studio Plus -- you just need to whitelist your phone number to go through the latest draft version instead of the published version. Click the Trigger widget and you can add as many phone numbers as you would like, separated with commas, to experience the latest draft version of the flow. 

Studio Test Users Dialogue

When you are pleased with the result, you can click Publish to make it accessible to everyone.

Widget Library

Current Widgets:

Trigger

Send & Wait For Reply

Split Based On...

Send Message

Say/Play

Gather Input On Call

Run Function

Make Outgoing Call

Connect Call To

Understand

HTTP Request

Record Call

 

💥  Trigger (Start)

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

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 section for more details.

⚙  Send & Wait For Reply

send-and-wait-for-reply

 

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.

Results:  Adds the following variables to the Engagement context (where “widgetname” is the name of your actual widget):

Variables:

outbound [The message Studio sent to the user]:

Sid

widgets.MY_WIDGET_NAME.outbound.Sid

External_id

widgets.MY_WIDGET_NAME.outbound.External_id

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

External_id

widgets.MY_WIDGET_NAME.inbound.External_id

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

 

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.



⚙  Send Message

send-message

 

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

Body

The text of the message to send.

 

 

Optional Configuration

Name

Description

Default

Message Sent From

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

Flow Default

 

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

 

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}}”

   

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.

   

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

Barge In

Stop playing media once Twilio receives a key press or speech.

True, False

True

Stop Gathering After ___ Seconds

Time to wait for the caller to press a key or say a word.

1s - 30s

5s

Stop Gathering On Keypress

A value that will submit the received data as soon as it’s pressed.

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

 

Speech Recognition Hints

A list of comma-separated hint values.

   



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

 

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: All Run Function requests are sent as Content-Type: application/x-www-form-urlencoded.

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.

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


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

 

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

 

Description:

Connect Call To allows you to bridge an in-progress call with another phone. Use this widget to connect your customer with a different department, or if they’re looking to reach a specific operator. 

Note: Support for connecting to Sip, SIM, Client, and Conference is coming soon!

Required Configuration:

The required fields for this Widget are Phone To Call and Number To Use as Caller ID, which can be variables or hard-coded phone numbers.

 

Name

Description

Default

Phone To Call

The phone number to call

 

Number to Use as Caller ID

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

⚙  Understand

understand

 

Description:

Understand allows you to apply machine learning to an input string to glean information and intent from it. Use this widget to extract user intent such as “positive” or “negative” from an incoming message, and use it to customize your flow and customer interactions even further.

 

Required Configuration:

The required fields for this Widget are Understand Service SID and Query, which can be variables or hard-coded numbers.

NOTE: The underlying Understand service itself is currently in developer preview. You must request access before using the Understand widget.

 

Name

Description

Understand Service SID

The SID of the Understand Service you would like to use

Query

Allows select/search of a variable from elsewhere in the flow, such as digits or speech result from a Gather Input on Call Widget.




⚙  HTTP Request  

http-request

 

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: All HTTP requests are sent as Content-Type: application/x-www-form-urlencoded.

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, POST, or PUT)

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

 

Optional Configuration:

You may optionally decide to declare a request body and HTTP parameters for the request initiated by 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.

 

Response:

The HTTP response from the URL must return a 2xx status code within 5 seconds.

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


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-voicemail

 

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

 

 

 

REST API

HTTP requests to Studio's REST API are protected with HTTP Basic authentication. To learn more about how Twilio handles authentication, please see our security documentation. You will use your Twilio account SID as the username and your auth token as the password for HTTP Basic authentication.

Important: When triggering flows with the API, don't forget to also configure your phone number with your Studio flow! If you don't configure the phone number, users won't be able to reply to your messages or interact with your IVR.

HTTP POST to Engagements

To trigger a new Engagement of your Flow via the REST API, make an HTTP POST request to:

https://studio.twilio.com/v1/Flows/{FlowSid}/Engagements

POST Parameters
Required Parameters

Parameter Description
To The Contact phone number to start a Studio Flow Engagement, available as variable {{contact.channel.address}}
From The Twilio phone number to send messages or initiate calls from during the Flow Engagement, available as variable {{flow.channel.address}}

Optional Parameters

Parameter Description
Parameters

JSON data that will be added to your flow's context and can accessed as variables inside your flow. For example, if you pass in Parameters={"name":"Zeke"} then inside a widget you can reference the variable {{flow.data.name}} which will return the string "Zeke".

Note: the JSON value must explicitly be passed as a string, not as a hash object. Depending on your particular HTTP library, you may need to add quotes or URL encode your JSON string. See curl examples below.

Examples:

Using curl on the command line, you can trigger a flow like so:

curl -X POST "https://studio.twilio.com/v1/Flows/FW9d816f0b90d2a10b913868462e339d29/Engagements" -d "To=+1646221xxxx" -d "From=+1331481xxxx" -u ACCOUNT_SID:AUTH_TOKEN 

To pass in additional custom data to your flow, add a Parameters= parameter.

curl -X POST "https://studio.twilio.com/v1/Flows/FW9d816f0b90d2a10b913868462e339d29/Engagements" -d "To=+1646221xxxx" -d "From=+1331481xxxx" -d "Parameters={\"name\":\"zeke\"}" -u ACCOUNT_SID:AUTH_TOKEN 

If you are using a Twilio helper library, you can trigger a flow like so:

Ruby:

Twilio::REST::Client.new(ACCOUNT_SID, AUTH_TOKEN).studio.flows('FW9d816f0b90d2a10b913868462e339d29').engagements.create(from: '+1331481xxxx', to: '1646221xxxx', parameters: '{"name":"Clément"}')

NodeJS:

TwilioClient.studio.flows('FW9d816f0b90d2a10b913868462e339d29').engagements.create({ to: '+1646221xxxx', from: '+1331481xxxx', parameters: JSON.stringify({name: "Clément"})}).then(function(engagement) { console.log(engagement.sid); });

PHP:

$flow = $client->studio->flows('FW9d816f0b90d2a10b913868462e339d29')->engagements->create('+1646221xxxx', '+1331481xxxx', array('parameters' => json_encode(array('name' => 'Clément'))));

The other helper libraries will be similar. Be sure you are using the latest version of the Twilio helper libraries. 

Guides

Ready to make your first Flow? We have some great Guides and videos for creating your first Studio flow for common use cases.

Troubleshooting

Here are some common gotchas and things to look out for when troubleshooting Studio:

  • Infinite loops are possible! We have a built in limit, so your flow won't go on forever -- it will stop on it's own eventually. But be careful whenever making transitions that loop back to themselves.
  • Returning custom TwiML from an HTTP Request or Function widget isn't yet supported. It will be soon.
  • Only API versions 2010-04-01 and later are supported. If your account is configured to use the deprecated 2008 API by default, be sure to upgrade your phone numbers to use a later API.

 

 

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.