Skip to contentSkip to navigationSkip to topbar
On this page

REST API v2



Introduction

introduction page anchor

With the Studio REST API you can trigger Flows programmatically for outbound use cases, manage Flow definitions for automated deployments, and retrieve information about Executions for reporting.

Triggering Flows Programmatically

triggering-flows-programmatically page anchor

Flows can respond to incoming calls and incoming messages, but you can also trigger a Studio Flow programmatically to initiate an outbound call or message. To trigger a Studio Flow for an outbound use case, use the REST API to create a new Execution. Creating a new Execution will fire the REST API trigger on your Flow and execute any connected widgets.

Common use cases for creating Executions via the REST API:

  • Initiating appointment reminders on a schedule
  • Notifying customers of an order delivery
  • Kicking off a survey for customer service feedback
  • Alerting workers of new task assignments

Using the Studio Canvas(link takes you to an external page) in Twilio Console, you can quickly build Studio Flows in a visual editing environment. With the new Studio REST API v2, you can now create, publish, and manage those same Flows programmatically without having to log in to Twilio Console.

Common use cases for managing Flows via the REST API:

  • Store Flows in your own version control
  • Integrate into CI/CD pipeline to automate Studio deployments
  • Programmatically move Flows between accounts or subaccounts
  • Swap Flow variables for use in different environments
  • Expose the ability to edit to end-users without having to grant them access to Console

Flows are defined as human-readable JSON objects and machine-validated against a set of JSON Schemas.

Try the Flows API Quickstart

If you want to dive right in, try our simple Flows API Quickstart to get a feel for fetching and updating Flows via the API and seeing how they look in the Studio Canvas in Console.

Get Started Now(link takes you to an external page)

Subscribe to Execution and Step Events

subscribe-to-execution-and-step-events page anchor

The Studio REST API provides methods to fetch Execution and Step data, but polling list endpoints for this data can be tedious. Instead, we recommend you subscribe to Studio Flow events through Event Streams to push the data to your own endpoint.


Differences Between v1 and v2

differences-between-v1-and-v2 page anchor

The Studio v2 API mirrors the existing v1 API but provides additional endpoints and methods for managing Flows, including the ability to read, create, update and validate Flow definitions. The Flow definition itself is now standardized as a JSON schema.

  • Flows resource in v2 has new Create, Update and Validate endpoints and additional properties.
  • The underlying JSON definition of a Flow is exposed as a public JSON Schema instead of an internal representation.
  • 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.
  • TestUsers resource is available to manage the contact addresses that can be used to test draft revisions of a Flow.
  • contact_sid is deprecated and will not be available in v2 Execution endpoint. Use contact_channel_address instead to uniquely track contacts.
  • Engagements endpoints were previously deprecated and are not included in v2. Use the Executions endpoints instead.

  • Request body when sending POST to Flows cannot be larger than 1 MB; thus, the Flow JSON definition itself must be less than 1 MB.

The standard Twilio server-side helper libraries and the Twilio CLI can be used to access the v2 endpoints. To access the v2 endpoints via the Twilio helper libraries, use the v2 namespace when referencing the client.

Example using the Node.js helper library:

1
const client = require('twilio')(accountSid, authToken);
2
3
client.studio.v2.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
4
.fetch()
5
.then(flow => console.log(flow.friendlyName));
(warning)

A note about upgrading the helper library

If you have already built your application on v1 and use the shortcut syntax in the helper libraries — specifically Node.js, PHP, Python, and Ruby — upgrading to the latest version will automatically update your code behind the scenes to reference the v2 API, which may be unexpected.

For example, if you currently use Node.js without the version indicator in the namespace, this will point to v2 after upgrade:

1
client.studio.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
2
.executions
3
.create({to: '+15558675310', from: '+15017122661'})
4
.then(execution => console.log(execution.sid));

To ensure your application references the correct version, add the version to the namespace:

1
client.studio.v1.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
2
.executions
3
.create({to: '+15558675310', from: '+15017122661'})
4
.then(execution => console.log(execution.sid));

And when you're ready to upgrade, update the namespace from v1 to v2:

1
client.studio.v2.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
2
.executions
3
.create({to: '+15558675310', from: '+15017122661'})
4
.then(execution => console.log(execution.sid));

Studio REST API v2 Resources

studio-rest-api-v2-resources page anchor
ResourceDescription
FlowAllows you to create, read and update Flows created in your account.
Flow RevisionProvides complete history of all changes to a Flow.
Flow ValidateAllows you to validate a Flow definition without creating a new revision.
Test UserAllows you to manage the contact addresses that can test draft versions of a Flow.
ExecutionsMirrors the existing v1 endpoint, allowing Executions to be created on demand and to retrieve historical logs.
Execution ContextMirrors the existing v1 endpoint
StepMirrors the existing v1 endpoint
Step ContextMirrors the existing v1 endpoint

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.