Menu

Studio User Guide

Twilio Studio is a visual low-code/no-code tool that enables anyone to design, deploy, and scale customer communications. Companies can now fast-track their customer engagement roadmap using the creative talent of all builders within their organization.

When to use Twilio Studio

Any builder can use Twilio Studio to quickly create and modify workflows with little to no code. Studio is designed for use by cross-functional teams as well as individuals who want to build communications tools. It provides a common framework for everyone to do the work they need to do and collaborate on a project using a single tool. 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 Twilio Functions).

Studio Features

  • Trigger Flows via inbound messages, inbound voice calls, webhooks, and other Studio Flows
  • Create, modify, and deploy Flows (Workflows)
  • Import and export Flows
  • Add and remove Transitions between Widgets
  • 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

Get Started

If you are new to using Twilio Studio, check out the Getting Started guide to familiarize yourself with the core concepts and mechanics of working with Studio. Once you are familiar with the Studio interface, you can come back to this guide for more detailed information about specific Widgets and actions you can perform with Studio.

Data Retention in Studio

Studio retains Execution and Step data for 30 days after an Execution starts. (Before October 1, 2021, we retained this data for 30 days after an Execution ended.) Once the data expires, it is unavailable via the Studio REST API and Twilio Console.

To access your Execution and Step logs past 30 days, use Event Streams to subscribe to Studio Flow events and log them in your own systems.

Active Executions that are still awaiting a response from your end user after 30 days will also be deleted. If your end user responds after their Execution is deleted, they will return to the top of the Flow and start a new Execution.

Studio Step logs, the resource that represent the runtime processing of a Widget, are best-effort delivery. This means that the network does not guarantee that this data will be delivered.

Data Retention for Underlying Products

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

PCI Compliance in Studio

Studio does not support the PCI Mode setting in Programmable Voice, however you can build PCI compliant Flows that process payments with Studio using the Capture Payments Widget.

Studio does not redact <Gather> data collected by the Gather Input Widget. To use <Gather> for collecting PCI sensitive data, use the TwiML Redirect Widget to redirect the call away from Studio to an external URL that can collect <Gather> data in a compliant way.

Learn more about Twilio's PCI Compliance.

Triggering Flows

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

  • Incoming Message
  • Incoming Call
  • REST API (Inbound Request)
  • Subflow

All four of these appear in the Trigger Widget, and you can drag and drop from one or more to reflect 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 from the Programmable Messaging API and sends it to your Studio Flow Webhook URL:

https://webhooks.twilio.com/v1/Accounts/{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. 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:

https://webhooks.twilio.com/v1/Accounts/{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.

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.

Incoming Conversation

The Incoming Conversation trigger is invoked when a Conversation invokes a Studio Webhook for a new message.

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 Conversation's identifier. For a Conversations Flow, Studio only allows a single active Execution per Conversation. All incoming messages from the Conversation to that Flow during an active Execution will be handled by that same Execution. Multiple participants of the same Conversation are, therefore, able to advance the same Execution.

Sending media is not supported when using the Conversations integration.

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

Subflow Trigger

To invoke a Flow as a Subflow, connect Widgets to the Subflow trigger. The Subflow trigger is invoked by the Run Subflow Widget.

See Studio Subflows for more details.

Working With Variables

As your Flow executes, it saves the state in 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 provides 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:

Liquid template with logic example

{% if flow.data.first_name %}
Hello {{flow.data.first_name}}
{% 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

Description Liquid Variable
The Flow's SID {{flow.flow_sid}}
The contact's SID for the current Flow Execution {{flow.sid}}
The Flow's address (e.g. Twilio phone number) {{flow.channel.address}}

Example Flow variables in JSON format:

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

Contact Variables

Description Liquid Variable
The user's address (e.g. handset phone number) {{contact.channel.address}}

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:

Description Liquid Variable
SID {{widgets.MY_WIDGET_NAME.message.Sid}}
To (User's Contact Address) {{widgets.MY_WIDGET_NAME.message.To}}
From (Studio Flow's Contact Address) {{widgets.MY_WIDGET_NAME.message.From}}
Body (Message content) {{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.

Subscribing to Flow Events with Event Streams

You can use Event Streams to subscribe to Execution and Step events from your Flow. Options for streaming Studio data include both Kinesis and traditional webhooks.

Use these events to log data, generate real-time reports, or trigger other actions:

com.twilio.studio.flow.execution.started
com.twilio.studio.flow.execution.ended
com.twilio.studio.flow.step.ended

Try the Event Streams Webhook Quickstart.

Testing Draft Flows

You can test a draft of your Studio Flow without publishing changes. To do this, click the Trigger Widget to open the Trigger Widget Inspector Panel. Then, add your phone number to the Test Users section. You can multiple phone numbers, separated by commas. Numbers should be in E.164 format.

When you use one of the numbers that you entered in the Test Users section to contact the Twilio Phone Number associated with this Studio Flow, the Flow will run through the latest draft Flow, rather than the latest published Flow.

Studio Test Users Dialogue

When you are finished testing, you can click Publish to make your changes 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 new 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 Flow.png

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

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.

Note that if you want to duplicate a Flow within your own account, it is best to use the Duplicate Flow method to create a copy of a Flow in the same account. Importing and exporting 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 and store it elsewhere.

Studio Flow JSON

Importing Flow Data

Create a new Flow, and select Import from JSON from the list of templates. Then, click Next.

Studio Import from JSON template

In the next window, you can paste the Flow JSON and click Next. This will create the new Flow as defined in the JSON you pasted.

Studio new flow with JSON importing

Troubleshooting

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 Step 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.
  • Flow Execution will be stopped if the same Widget is executed 10 times in a row.
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more