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 responding to messages or hang up their call.
The Execution resource can be used to retrieve information about existing Executions or to create new Executions for outbound use cases (e.g. surveys, appointment reminders).
Subscribe to Real-time Studio Events
You can now subscribe to Studio Events for Executions and Steps instead of polling via the REST API. Simplify your data ingestion with Event Streams for Studio.
Studio Rate Limits
Be sure to review Studio's rate limits when building your application.
Required Parameters
Parameter
Description
To
The Contact phone number (or other identifier) to start a Studio Flow Execution, available as variable {{contact.channel.address}}
From
The Twilio phone number (or other identifier such as a SID of a Messaging Service) to send messages or initiate calls from during the Flow Execution, available as variable {{flow.channel.address}}
Important: If you are using a phone number as an identifier, make sure to format the To / From phone numbers as E.164 (e.g. +1xxxxxxxxxx) to ensure a Contact's session is tracked correctly. Only one Execution can be active at a time for the same To/From combination.
Optional Parameters
Parameter
Description
Parameters
JSON data that will be added to your flow's context and can be 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: At the HTTP layer, the JSON parameter must be explicitly passed as a URL encoded string. However, the Twilio Helper Libraries accept a native object and automatically serialize and encode the JSON string for you.
Important: When triggering flows with the API, don't forget to also configure your phone number (or other identifier) 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.
Additionally, if a number is configured with a Messaging Service, be sure to use the Messaging Service identifier as the From identifier so that users can reply to your messages, and ensure that your Messaging Service inbound settings are configured to point to the webhook urlfrom your Twilio Studio Flow.
The phone number, SIP address or Client identifier that triggered the Execution. Phone numbers are in E.164 format (e.g. +16175551212). SIP addresses are formatted as name@company.com. Client identifiers are formatted client:name.
The current state of the Flow's Execution. As a flow executes, we save its state in this context. We save data that your widgets can access as variables in configuration fields or in text areas as variable substitution.
POST https://studio.twilio.com/v2/Flows/{FlowSid}/Executions
Creating a new Execution will attempt to trigger a new Studio flow between two contacts.
(warning)
Warning
Handling Conflicting Executions: New Behavior in v2
If you attempt to create an Execution using v2 of this API and we find there is an active Execution for the same To/From combination, the API will return an error with the 409 Conflict HTTP status. This error response will provide a reference to the existing Execution SID so you can end it, if appropriate, and try your Create request again.
If we are able to create a new Execution with your To/From information, the API will return the 201 Created HTTP status.
If you're still using v1 of this API, creating an Execution where one is already active will not create a new Execution or return an error, and will instead always return a 200 OK code with the existing active Execution.
The Twilio phone number to send messages or initiate calls from during the Flow's Execution. Available as variable {{flow.channel.address}}. For SMS, this can also be a Messaging Service SID.
JSON data that will be added to the Flow's context and that can be accessed as variables inside your Flow. For example, if you pass in Parameters={"name":"Zeke"}, a widget in your Flow can reference the variable {{flow.data.name}}, which returns "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 the JSON string.
Create Execution
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
Create a new Execution with JSON data to be added to your flow's context. You will be able to access these parameters as variables inside your Studio flow.
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
POST https://studio.twilio.com/v2/Flows/{FlowSid}/Executions/{Sid}
An active Execution can be updated to ended using the REST API. Once ended, subsequent widgets in the Flow are not processed, and any new events that Studio receives for that Execution are rejected.
(information)
Info
Attempting to end an Execution that is already in the ended state will fail with a 409 Conflict.