Execution
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).
Create an Execution to Trigger a Flow
To trigger a new Execution of your Flow via the REST API, make an HTTP POST request to:
https://studio.twilio.com/v2/Flows/{FlowSid}/Executions
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) to send messages or initiate calls from during the Flow Execution, available as variable {{flow.channel.address}} |
Important: The To and From phone numbers must be formatted 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 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. |
Quick Example
Here is a quick example of creating an Execution via the REST API using the Twilio Node.js Helper Library:
const client = require('twilio')(accountSid, authToken); client.studio.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX') .executions .create({ to: '+15558675310', from: '+15017122661', parameters: { name: 'Zeke' }}) .then(execution => console.log(execution.sid));
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.
See the following for examples:
- Configure a Twilio Phone Number to Receive and Respond to Messages
- Configure a Twilio Phone Number to Receive and Respond to Voice Calls
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 Messsaging Service inbound settings are configured to point to the webook url from your Twilio Studio Flow.
Execution properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the Execution resource. |
account_sid
|
The SID of the Account that created the Execution resource. |
flow_sid
|
The SID of the Flow. |
contact_channel_address
|
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 |
context
|
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. |
status
|
The status of the Execution. Can be: |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
url
|
The absolute URL of the resource. |
links
|
The URLs of nested resources. |
Create a new execution
https://studio.twilio.com/v2/Flows/{FlowSid}/Executions
New behavior in v2
Creating an Execution via the v2 API for a Contact that is already in an active Execution will fail with a 409 Conflict. The detailed error response provides a reference to the conflicting Execution so you can end it via the API and then retry the request.
When creating an Execution in v1 there is no indication that an Execution is already active for the same Contact, and the new Execution is not created. Instead, the API simply returns the existing active Execution.
Parameters
| Parameters in REST API format | |
|---|---|
flow_sid
Path
|
The SID of the Excecution's Flow. |
to
Required
|
The Contact phone number to start a Studio Flow Execution, available as variable |
from
Required
|
The Twilio phone number to send messages or initiate calls from during the Flow's Execution. Available as variable |
parameters
Optional
|
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 |
Example 1
Example 2
Fetch a single execution
https://studio.twilio.com/v2/Flows/{FlowSid}/Executions/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
flow_sid
Path
|
The SID of the Flow with the Execution resource to fetch |
sid
Path
|
The SID of the Execution resource to fetch. |
Example 1
Read a list of executions
https://studio.twilio.com/v2/Flows/{FlowSid}/Executions
Execution resources are listed in reverse chronological order (most recent is first).
Parameters
| Parameters in REST API format | |
|---|---|
flow_sid
Path
|
The SID of the Flow with the Execution resources to read. |
date_created_from
Optional
|
Only show Execution resources starting on or after this ISO 8601 date-time, given as |
date_created_to
Optional
|
Only show Execution resources starting before this ISO 8601 date-time, given as |
Example 1
Example 2
Update an Execution
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.
Parameters
| Parameters in REST API format | |
|---|---|
flow_sid
Path
|
The SID of the Flow with the Execution resources to update. |
sid
Path
|
The SID of the Execution resource to update. |
status
Required
|
The status of the Execution. Can only be |
Example 1
Delete an execution
https://studio.twilio.com/v2/Flows/{FlowSid}/Executions/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
flow_sid
Path
|
The SID of the Flow with the Execution resources to delete. |
sid
Path
|
The SID of the Execution resource to delete. |
Example 1
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.