Menu

Expand
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?

Execution

BETA

This Twilio product is currently available as a beta release. Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by a Twilio SLA. Learn more about beta product support.

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.

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.

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

Execution properties

Resource Properties in REST API format
sid
sid<FN> Not PII

The unique string that we created to identify the Execution resource.

account_sid
sid<AC> Not PII

The SID of the Account that created the Execution resource.

flow_sid
sid<FW> Not PII

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 name@company.com. Client identifiers are formatted client:name.

context
object Not PII

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
enum:status Not PII

The status of the Execution. Can be: active or ended.

date_created
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

url
url Not PII

The absolute URL of the resource.

links
uri_map Not PII

The URLs of nested resources.

Create a new execution

post
https://studio.twilio.com/v2/Flows/{FlowSid}/Executions

New behavior in v2

Creating an Execution via the REST API for a Contact that is already in an active Execution will now fail with a 409 Conflict and will reference the conflicting Execution, which can then be ended via the API, if desired. In v1, there was no indication that an Execution was already active for that Contact.

Parameters
Parameters in REST API format
flow_sid
Path
post sid<FW> Not PII

The SID of the Excecution's Flow.

to
Required
post phone_number Not PII

The Contact phone number to start a Studio Flow Execution, available as variable {{contact.channel.address}}.

from
Required
post phone_number Not PII

The Twilio phone number to send messages or initiate calls from during the Flow's Execution. Available as variable {{flow.channel.address}}.

parameters
Optional
post object PII MTL: 90 DAYS

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.

Example 1
        
        
        
        
        Example 2
              
              
              
              
              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.

              Create an Execution with custom parameters

              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.

              Fetch a single execution

              get
              https://studio.twilio.com/v2/Flows/{FlowSid}/Executions/{Sid}
              Parameters
              Parameters in REST API format
              flow_sid
              Path
              get sid<FW> Not PII

              The SID of the Flow with the Execution resource to fetch

              sid
              Path
              get sid<FN> Not PII

              The SID of the Execution resource to fetch.

              Example 1
                    
                    
                    
                    

                    Read a list of executions

                    get
                    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
                    get sid<FW> Not PII

                    The SID of the Flow with the Execution resources to read.

                    date_created_from
                    Optional
                    get date_time<iso8601> Not PII

                    Only show Execution resources starting on or after this ISO 8601 date-time, given as YYYY-MM-DDThh:mm:ss-hh:mm.

                    date_created_to
                    Optional
                    get date_time<iso8601> Not PII

                    Only show Execution resources starting before this ISO 8601 date-time, given as YYYY-MM-DDThh:mm:ss-hh:mm.

                    Example 1
                          
                          
                          
                          
                          Example 2
                                
                                
                                
                                
                                Executions can be filtered by the date they were created (30-day max range).

                                Read Executions Filtered by Date

                                Executions can be filtered by the date they were created (30-day max range).

                                Update an Execution

                                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.

                                Parameters
                                Parameters in REST API format
                                flow_sid
                                Path
                                post sid<FW> Not PII

                                The SID of the Flow with the Execution resources to update.

                                sid
                                Path
                                post sid<FN> Not PII

                                The SID of the Execution resource to update.

                                status
                                Required
                                post ienum:status Not PII

                                The status of the Execution. Can only be ended.

                                Example 1
                                      
                                      
                                      
                                      

                                      Delete an execution

                                      delete
                                      https://studio.twilio.com/v2/Flows/{FlowSid}/Executions/{Sid}
                                      Parameters
                                      Parameters in REST API format
                                      flow_sid
                                      Path
                                      delete sid<FW> Not PII

                                      The SID of the Flow with the Execution resources to delete.

                                      sid
                                      Path
                                      delete sid<FN> Not PII

                                      The SID of the Execution resource to delete.

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