Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

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?

REST API

The Studio REST API lets you trigger flows programmatically and also retrieve information about your flows and executions. The Incoming Request Trigger on your flow will fire when you create an Execution via the REST API. 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.

HTTP POST to create an Execution

To trigger a new Execution of your Flow via the REST API, make an HTTP POST request to:

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

POST Parameters
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: 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 your JSON string. See curl examples below.

Quick Examples:

Using curl on the command line, you can trigger a flow like so:

curl -X POST "https://studio.twilio.com/v1/Flows/FW9d816f0b90d2a10b913868462e339d29/Executions" -d "To=+1646221xxxx" -d "From=+1331481xxxx" -u ACCOUNT_SID:AUTH_TOKEN 

To pass in additional custom data to your flow, add a Parameters= parameter.

curl -X POST "https://studio.twilio.com/v1/Flows/FW9d816f0b90d2a10b913868462e339d29/Executions" -d "To=+1646221xxxx" -d "From=+1331481xxxx" -d "Parameters={\"name\":\"zeke\"}" -u ACCOUNT_SID:AUTH_TOKEN

If you are using a Twilio helper library, you can trigger a flow like so:

Ruby:

Twilio::REST::Client.new(ACCOUNT_SID, AUTH_TOKEN).studio.flows('FW9d816f0b90d2a10b913868462e339d29').executions.create(from: '+1331481xxxx', to: '1646221xxxx', parameters: '{"name":"Clément"}')

NodeJS:

TwilioClient.studio.flows('FW9d816f0b90d2a10b913868462e339d29').executions.create({ to: '+1646221xxxx', from: '+1331481xxxx', parameters: JSON.stringify({name: "Clément"})}).then(function(execution) { console.log(execution.sid); });

PHP:

$twilio->studio->v1->flows("FW9d816f0b90d2a10b913868462e339d29")->executions->create("+1646221xxxx", "+1331481xxxx", array("parameters" => array("foo" => "bar")));

The Executions resource page documents examples in other languages. For information on the other resources, check out the full REST API documentation for each resource below.

Studio REST API resources

Flow

Allows you to retrieve a list of Flows created in your account.

Execution

Allows you to create Executions that will act on the incoming REST API trigger for the Flow specified.

Execution Context

The execution context gives a JSON representation of your flow and its widgets at the time of execution.

Step

Each move through your flow is a Step. The Steps resource allows you to retrieve the steps for a given execution.

Step Context

Step context ties a JSON representation of data parsed as part of an individual widget.

Authentication

HTTP requests to the REST API are protected with HTTP Basic Authentication like other Twilio REST APIs. To learn more about how Twilio handles authentication, please refer to our security documentation.

To authenticate, you will need your Account SID and Auth Token from the Twilio Console:

Twilio Account Summary section of the console

You will use your Twilio Account SID as the username and your Auth Token as the password for HTTP Basic authentication.

Helper libraries

If you use one of our helper libraries for C#, Java, Node.js, PHP, Python, or Ruby; you needn't worry about the URL for the API or how to do HTTP Basic authentication. The helper libraries take care of it for you.

Engagements name change and deprecation

During the beta of Twilio Studio (prior to August 1st 2018), flow Executions were named Engagements, and we had an API available for creating Engagements. We got feedback that the word engagements was confusing, so we've changed it: We have renamed Engagements to Executions across the Studio product and API but maintained support for Engagements during this transition. There is no functional difference between /Engagements and /Executions in the API. The Engagements API endpoint is now deprecated:

  • /Engagements will continue to function as is until the end of 2018.
  • Customers should move to /Executions (available via REST and in Twilio helper libraries)
  • The /Engagements API endpoint will cease to function in January 2019 and be removed from new versions of the Twilio helper libraries at that time.
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.