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?

Usage Guide


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 Deploy Flows (Workflows)
  • Import and Export Flows
  • Add and Remove Transitions
  • Manage Widget Settings with the Inspector Panel
  • Define Transitions to Advance Users through Flows
  • Create and Pass Variables
  • View Executions (Individual runs through flows)
  • Organize Use Cases and Logic in Separate Flows

Getting Started

You can start using Studio by logging in and visiting the Studio homepage in the Twilio console.


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





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.


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.


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.


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.


An Execution represents a specific person’s run through a Flow. An Execution 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 Execution is created to represent my call to that number / path through the Flow. The owner of the Flow can see my Execution, as well as the Executions of other users who have run through the Flow.

Data Retention in Studio

Studio retains Execution logs for 30 days after Executions end. However, Executions that have not ended within 60 days of being created are considered stuck. Studio automatically ends and deletes stuck Executions 60 days after they were created. Once Executions are deleted, they are no longer accessible via Console or the API.

Log data is persisted in Studio for 30 days after an execution ends. This relates to all execution step data persisted by the application. Data relating to underlying products used via Studio, such as SMS or voice call logs, are not automatically deleted at the same time as execution data. Data generated by other products is retained / deleted in line with those products' data policies. Details of individual product data retention policies can be found in the specific product documentation, such as here for SMS and here for voice calls.

Handling concurrent calls from the same number in Studio

The concurrent calls setting only applies to Executions created via the Incoming Call trigger type. Incoming Message and REST API triggered Executions are not affected.

Note: This functionality changed on October 1st 2018. New flows created after this date will handle concurrent calls from the same caller ID by default. For flows created before that date, the switch must be made manually in the call trigger (see screenshot below).

By default, Studio flows can handle inbound concurrent calls from the same number. The Send and Wait For Reply widget cannot be attached anywhere downstream of the Incoming Call trigger point. This is because if multiple users are calling from the same number, Studio can't uniquely text back one user in an active execution and correctly identify a reply, because callers all share the same number.

For certain specific use cases, where you know callers to a Studio flow will always have a unique visible caller ID, you can disable the concurrent calls mode via the Advanced Features dropdown in the Trigger widget (see below). When disabled, you will be able to add the Send and Wait for Reply widget to incoming call trigger connected flows. This is only recommended for advanced users who know that their flow is triggered from visible unique caller IDs.

Enabling Concurrent Calls in Studio

Note: Concurrent Calls does not apply to Executions triggered by an Incoming Message or the REST API. Those trigger types can only handle one concurrent Execution per Contact to ensure each session is uniquely tracked.

Using Studio

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.

Navigating the Canvas

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

Working With Widgets

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.

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

Keyboard shortcuts are available if you'd like to duplicate widgets on the canvas. Simply select a widget (it will highlight in blue) and then copy (Cmd + C on Mac or Ctrl +C on Windows) and paste (Cmd + V on Mac or Ctrl + V on Windows).

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.

Do not use Personally Identifiable Information in Flow names or Widget names

You should not use directly identifying information (aka personally identifiable information or PII) like a person's name, home address, email or phone number, etc., in Flow names or Widget Names because the systems that will process this attribute assume it is not directly identifying information. You can read more about how we process your data in our privacy policy.

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.

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.


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 Call
  • REST API (Inbound Request)

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


Incoming Message

The Incoming Message trigger is invoked when your Twilio Phone Number (or other message-based channel) receives a new message and sends it to your Studio Flow Webhook URL:{AccountSid}/Flows/{FlowSid}

By connecting Send Message or Send & Wait for Reply widgets, you can respond to those incoming messages and carry on a conversation with the Contact.

Studio maintains a unique session based on the Contact's identifier (usually a phone number). For a messaging Flow, Studio only allows a single active Execution per Contact. Thus, all messages from the Contact to that Flow during an active Execution will be handled by that same Execution.

Incoming Call

The Incoming Call trigger is invoked when your Twilio Phone Number (or other voice-based channel) receives a new call and sends it to your Studio Flow Webhook URL:{AccountSid}/Flows/{FlowSid}

By connecting voice widgets, such as Say/Play and Gather Input, you can guide the Contact through a series of interactive voice responses (IVR) and even connect the Contact to another party with Connect Call To or route them to Record Voicemail.

By default Studio maintains a unique voice session based on the combination of the Contact's identifier (usually a phone number) and the unique Call SID, ensuring every call is handled uniquely, even if concurrent calls use the same Caller ID.

REST API Trigger

Using the Studio REST API, you can trigger an outbound call or message to a Contact. Use this trigger type to initiate appointment reminders, surveys or alerts from your own application. Add widgets to the REST API trigger to control the conversation just as you would for Incoming Message or Incoming Call.

For outbound voice calls, use the Make Outgoing Call widget to initiate the call; for oubound messages, use either Send Message to fire and forget or Send & Wait for Reply to initiate a two-way conversation.

Studio maintains a unique session based on the Contact's identifier (usually a phone number). For a REST API Flow, Studio only allows a single active Execution per Contact. If an Execution is already active for a Contact, a new REST API request for that same Contact will simply return the existing Execution.

Tip: Be sure the To and From phone numbers are formatted as E.164 (e.g. +1xxxxxxxxxx) to ensure correct session tracking.

See the Studio REST API docs for more details.

Join the Studio v2 REST API Pilot!

Request an Invitation

The Studio v2 REST API is now in pilot phase and includes the ability to programmatically create and update Flows! We are looking for customers to evaluate the new API and provide feedback.

If you would like to participate, please contact Twilio Support to request an invitation.

Configuring Your Twilio Number for Studio

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.

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

Note: A Twilio phone number can only route inbound messages and calls to a single Studio Flow (one-to-one), but that Flow can process messages and calls from multiple phone numbers (one-to-many).


Important: For Voice Flows, add the Studio Flow Webhook URL to both the Call Status Changes and the Primary Handler Fails fields to ensure Studio can always correctly detect the end of the call.

Studio Webhook Call Status Changes

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

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

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

Hello {{}}

{% else %}

Hello friend

{% endif %}

Note: Liquid template variables can render up to 16KB strings max.

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 Execution Sid: flow.sid

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

Example Flow variables in JSON format:

    "flow": {
        "flow_sid": "FWxxxx",
        "channel": {
            "address": "+1xxxxxxxxxx"
        "sid": "FNxxxxx"

Contact Variables include:

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

Widget Variables

After execution, many widgets publish data variables to the Execution 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

Note: This functionality has recently been updated. Previously, Flow edits published automatically for users on the Studio starter plan. We've now added the below Draft/Edit functionality for all Studio plan users, including the free Starter tier.

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 also includes Revision History. You will be able to see a list of every change made to your flow and the differences between the currently published version and the latest draft.

Testing Draft Flows

Testing draft flows is easy with Studio -- you just need to make your phone number 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.

Renaming Flows

To change the name of your Flow, click on the Trigger widget. The right-side configuration panel includes a field for Flow Name. Enter the desired name, and click Save to rename your Flow.

Renaming Studio Flows

Duplicating Flows

To make a copy of an existing Flow, navigate to your list of Flows and locate the one you'd like to copy. Click on Duplicate Flow and a new copy of the Flow will be created and automatically opened.

Duplicate a Studio Flow

Deleting Flows

If you'd like to delete a Flow, navigate to your list of Flows and locate the one you'd like to remove. Click on Delete Flow to remove the Flow.

Delete a Studio flow

Caution: Deleting a Flow is not recoverable. If you delete a Flow that is being used in production to handle calls or messages, you will need to rebuild the Flow to restore service.

Importing and Exporting Flows

Use this functionality to export flow definitions as JSON and import them to other Twilio accounts. It's best to use Duplicate flow for simply creating a copy of a Flow in the same account. Import / Export of Flows is intended for exporting a flow to store elsewhere, e.g. source control and/or to move flows between Twilio accounts.

Import/Export via the REST API v2

Try the Quickstart

Import and export functionality for Flows is also available via the REST API v2. Check out the Flows API Quickstart to learn how to export the Flow JSON and import it into a new Flow via the REST API and helper libraries.

Your Studio Flow definition may reference other Twilio resources (like phone numbers, Functions, etc.). These references are not automatically copied when the Flow is imported to another account, and you may need to make manual updates to your Flow to refresh references to those resources.

Exporting Flow Data

Click on the Trigger widget and select Show Flow JSON.

Export Flow Trigger

This will display the JSON data that defines your flow. You can copy this data out and store it elsewhere.


Importing Flow Data

Create a new Flow, and select Import from JSON.

New flow from JSON

Click Next. You will be presented with a code window to paste valid Flow JSON.

Paste import JSON

Click Next to create the new Flow once the JSON definition is added.


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

  • Sometimes Executions become stuck for Inbound Calls. Follow our best practices to avoid stuck Executions.
  • 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.
  • Infinite loops are possible! We have a built-in limit, so your Execution will end after 1,000 steps. But be careful when creating loops over a set of widgets.
  • Returning custom TwiML from an HTTP Request widget isn't supported. Instead, follow this guide for returning custom TwiML from a Run Function widget or use the Add TwiML Redirect widget.
  • Flows are limited to a maximum of 1,000 widgets for published Flows.
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.