Execution Resource
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.
HTTP requests to Studio's REST API are protected with HTTP Basic authentication(link takes you to an external page) . To learn more about how Twilio handles authentication, please see our security documentation . You will use your Twilio account SID as the username and your auth token as the password for HTTP Basic authentication.
Warning When triggering flows with the API, don't forget to also configure your Twilio 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 call back to your IVR.
Deprecation Notice The contact_sid
property has been deprecated and will be replaced with a static placeholder value in the v1 API. Use contact_channel_address
instead to uniquely track contacts. For the best experience and latest features, upgrade to the v2 API .
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 .
Resource properties sid
type: SID<FN>
The unique string that we created to identify the Execution resource.
Pattern:
^FN[0-9a-fA-F]{32}$
flow_sid
type: SID<FW>
The SID of the Flow.
Pattern:
^FW[0-9a-fA-F]{32}$
contact_sid
type: SID<FC>
The SID of the Contact.
Pattern:
^FC[0-9a-fA-F]{32}$
contact_channel_address
type: string
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
type: object
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
type: enum<string>
The status of the Execution. Can be: active
or ended
.
Possible values:
active
ended
date_created
type: string<date-time>
date_updated
type: string<date-time>
url
type: string<uri>
The absolute URL of the resource.
links
type: object<uri-map>
The URLs of nested resources.
POST https://studio.twilio.com/v1/Flows/{FlowSid}/Executions
URI parameters FlowSid
type: SID<FW>
The SID of the Excecution's Flow.
Pattern:
^FW[0-9a-fA-F]{32}$
Request body parameters To
type: string<phone-number> Required
The Contact phone number to start a Studio Flow Execution, available as variable {{contact.channel.address}}
.
From
type: string<phone-number> Required
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.
Parameters
type: object
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.
_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
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .create({to: '+15558675310', from: '+15017122661'})
_11 .then(execution => console.log(execution.sid));
_16 "url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "contact_sid": "FCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "contact_channel_address": "+18001234567",
_16 "date_created": "2015-07-30T20:00:00Z",
_16 "date_updated": "2015-07-30T20:00:00Z",
_16 "steps": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Steps",
_16 "execution_context": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Context"
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.
_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
_13 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13 const authToken = process.env.TWILIO_AUTH_TOKEN;
_13 const client = require('twilio')(accountSid, authToken);
_13 client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_13 .create({parameters: {
_13 }, to: '+15558675310', from: '+15017122661'})
_13 .then(execution => console.log(execution.sid));
_16 "url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "contact_sid": "FCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "contact_channel_address": "+18001234567",
_16 "date_created": "2015-07-30T20:00:00Z",
_16 "date_updated": "2015-07-30T20:00:00Z",
_16 "steps": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Steps",
_16 "execution_context": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Context"
GET https://studio.twilio.com/v1/Flows/{FlowSid}/Executions/{Sid}
URI parameters FlowSid
type: SID<FW>
The SID of the Flow with the Execution resource to fetch
Pattern:
^FW[0-9a-fA-F]{32}$
Sid
type: SID<FN>
The SID of the Execution resource to fetch.
Pattern:
^FN[0-9a-fA-F]{32}$
_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
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .executions('FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .then(execution => console.log(execution.sid));
_16 "sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "contact_sid": "FCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "contact_channel_address": "+14155555555",
_16 "date_created": "2017-11-06T12:00:00Z",
_16 "date_updated": null,
_16 "url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "steps": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Steps",
_16 "execution_context": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Context"
GET https://studio.twilio.com/v1/Flows/{FlowSid}/Executions
Execution resources are listed in reverse chronological order (most recent is first).
URI parameters FlowSid
type: SID<FW>
The SID of the Flow with the Execution resources to read.
Pattern:
^FW[0-9a-fA-F]{32}$
DateCreatedFrom
type: string<date-time>
DateCreatedTo
type: string<date-time>
PageSize
type: integer
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Page
type: integer
The page index. This value is simply for client state.
PageToken
type: string
The page token. This is provided by the API.
_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
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .then(executions => executions.forEach(e => console.log(e.sid)));
_12 "previous_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12 "next_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=1",
_12 "url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12 "first_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
Executions can be filtered by the date they were created (30-day max range).
_15 // Download the helper library from https://www.twilio.com/docs/node/install
_15 // Find your Account SID and Auth Token at twilio.com/console
_15 // and set the environment variables. See http://twil.io/secure
_15 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15 const authToken = process.env.TWILIO_AUTH_TOKEN;
_15 const client = require('twilio')(accountSid, authToken);
_15 client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15 dateCreatedFrom: new Date(Date.UTC(2019, 1, 17, 0, 0, 0)),
_15 dateCreatedTo: new Date(Date.UTC(2019, 1, 18, 0, 0, 0)),
_15 .then(executions => executions.forEach(e => console.log(e.sid)));
_12 "previous_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12 "next_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=1",
_12 "url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
_12 "first_page_url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions?PageSize=50&Page=0",
POST https://studio.twilio.com/v1/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.
URI parameters FlowSid
type: SID<FW>
The SID of the Flow with the Execution resources to update.
Pattern:
^FW[0-9a-fA-F]{32}$
Sid
type: SID<FN>
The SID of the Execution resource to update.
Pattern:
^FN[0-9a-fA-F]{32}$
Request body parameters Status
type: enum<string> Required
The status of the Execution. Can only be ended
.
Possible values:
active
ended
_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
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .executions('FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11 .update({status: 'ended'})
_11 .then(execution => console.log(execution.sid));
_16 "url": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "sid": "FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "flow_sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "contact_sid": "FCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_16 "contact_channel_address": "+14155555555",
_16 "date_created": "2017-11-06T12:00:00Z",
_16 "date_updated": "2017-11-06T12:00:00Z",
_16 "steps": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Steps",
_16 "execution_context": "https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions/FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Context"
DELETE https://studio.twilio.com/v1/Flows/{FlowSid}/Executions/{Sid}
URI parameters FlowSid
type: SID<FW>
The SID of the Flow with the Execution resources to delete.
Pattern:
^FW[0-9a-fA-F]{32}$
Sid
type: SID<FN>
The SID of the Execution resource to delete.
Pattern:
^FN[0-9a-fA-F]{32}$
_10 // Download the helper library from https://www.twilio.com/docs/node/install
_10 // Find your Account SID and Auth Token at twilio.com/console
_10 // and set the environment variables. See http://twil.io/secure
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .executions('FNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')