REST API v2

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

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.

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.

• The 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's already in an active Execution now fails with a 409 Conflict error and references the conflicting Execution. You can then choose to end that Execution using the API. In v1, there wasn't any indication that an Execution was already active for a contact.
• The TestUsers resource is available to manage the contact addresses you can use to test draft revisions of a Flow.
• contact_sid is deprecated and is no longer available in the v2 Execution endpoint. Instead, use contact_channel_address 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. Because of this, the Flow JSON definition itself must be less than 1 MB.

You can use the standard Twilio server-side SDKs and the Twilio CLI to access the v2 endpoints. To access the v2 endpoints via the Twilio SDKs, use the v2 namespace when referencing the client.

Example using the Node.js SDK:

1
const client = require('twilio')(accountSid, authToken);
2

3
client.studio.v2.flows('FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
4
                .fetch()
5
                .then(flow => console.log(flow.friendlyName));

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

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

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