Automate Flow deployments with the Studio REST API v2, now in beta

Automate Flow deployments with the Studio REST API v2, now in beta

Twilio Studio has enabled thousands of developers to build and deploy complex communication workflows quickly and scale effortlessly on Twilio Runtime, our Serverless environment. Today Studio has made publishing and deployment of Flows even more powerful.

We are pleased to announce the beta release of the Studio REST API v2, providing full support for publishing of Flows via the REST API, Twilio’s helper libraries, and the Twilio CLI.

With the new Flows endpoint in v2, you can now easily

• Test and deploy Flows through development, staging and production environments
• Templatize Flows to quickly provision new subccounts
• Integrate with your CI/CD pipeline for automated deployments and rollback
• Update Studio Flows as part of a larger, more complex Twilio deployment (e.g. Flex)
• Create your own custom, branded Studio front-end UI!

What customers are saying

Ciptex has used v2 of the Studio API to power RACE, our fast track Contact Centre platform which was designed and built to support businesses with technology and workflow challenges preventing home working during COVID-19 lockdown.

The flexibility the API gives us to modify Studio Flows in near real-time has opened up new possibilities for our product set, meaning we can deploy RACE in under 15 minutes from online signup.

—Matthew Duggan, Head of DevOps, Ciptex

How it works

A Studio Flow is represented behind the scenes as a JSON object, containing all the widgets and properties necessary for executing your workflows and for rendering the Flow visually in the Studio Canvas.

Take this simple “hello world” Flow as an example. Here’s how it looks on the Studio Canvas:

You can see the underlying JSON definition via the Trigger widget’s “Show Flow JSON” button in the UI:

With the Studio REST API v2, this same JSON definition is now accessible via the Flows endpoint, enabling you to fetch, manipulate, and save changes back to the Flow from your own code in addition to the Studio Canvas.

Let’s take a look at how the API works.

Fetch the definition

Here’s a simple one-liner to output just the definition from the API response:

Save a new draft of the Flow

To save a new draft of the Flow, just pass in the new definition to the Update method. For brevity, you can pass in the definition as a variable or from a file location:

Validate the Flow definition

Because Flow definitions can become large, complex blobs of JSON, the API also provides a validation endpoint that allows you to test the validity of your Flow definition against our backend without having to actually create or update a real Flow. This is particularly handy if you want to create your own custom front-end and validate end user input before saving.

The Validate endpoint accepts the same parameters as Create and Update, so you can use the same payload to validate the JSON as you do to save the Flow as a new revision.

Revisions, publishing, and rollback

Every change to a Flow, whether through the UI or the API, is saved as an immutable revision, allowing you to track every change over time and to easily roll back (or roll forward) to any revision of the Flow instantly.

Working with revisions

Flow revisions can be listed via the UI:

And now Flow revisions can be listed via the API:

And just like loading a Flow in the Studio Canvas, fetching a Flow via the API always returns the latest revision:

As a convenience, to fetch the current published revision, use the magic identifier LatestPublished as the revision:

Publishing a Flow

Publishing a Flow makes a specific revision live and ready to receive calls, messages, or process requests from the REST API. Publishing occurs when you create or update a Flow and specify the status as “published.”

Just like when you click the Publish button in the Studio Canvas, the API provides a shortcut for publishing the head revision of a Flow in a single request:

Rolling back a Flow

To roll back a Flow to a specific revision, fetch the revision you want to use and update the Flow with that revision’s definition and set the status to “published”:

Test Users

To test new changes to a Flow before publishing, the UI lets you specify a list of phone numbers (or other identities) to allow. Calls and messages from those numbers will run against the latest draft revision of the Flow.

Using the API, you can manage test users per Flow in the same way, giving you programmatic control over who can test drafts.

Fetch the existing Test Users of a Flow:

Update the Test Users of a Flow:

Next Steps

The Studio REST API v2 is already available in all the Twilio helper libraries and the CLI. Be sure to upgrade your development environment to the latest helper library version or the CLI to get access to these beta features.

Check out the complete docs for more details and try the quickstart to get up and running with the API fast!

Zack Pitts is the Product Manager for Twilio Studio. He can be reached at zpitts [at] twilio.com.