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

April 30, 2020
Written by
Zack Pitts

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:

"Hello world" Flow in Studio

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

"Hello world" JSON definition

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.

Follow the samples with the Twilio CLI

The samples in this post use the Twilio CLI to illustrate the methods. If you’re not already using the CLI, check out the quickstart.

Fetch the definition

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

twilio api:studio:v2:flows:fetch --sid FW20bcee1211df5e936c014d11519e1aef -o json | jq '.[0].definition'

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:

twilio api:studio:v2:flows:update \
        --sid FW20bcee1211df5e936c014d11519e1aef \
        --commit-message "new draft" \
        --status draft \
        --definition "`echo $DEFINITION`"

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.

twilio api:studio:v2:flows:validate:create \
   --friendly-name "Demo" \
   --status published \
   --definition "`echo $DEFINITION`

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:

Flow revision history

And now Flow revisions can be listed via the API:

twilio api:studio:v2:flows:revisions:list --sid FW20bcee1211df5e936c014d11519e1aef --limit 5

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

twilio api:studio:v2:flows:fetch --sid FW20bcee1211df5e936c014d11519e1aef

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

twilio api:studio:v2:flows:revisions:fetch --sid FW20bcee1211df5e936c014d11519e1aef --revision LatestPublished

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:

twilio api:studio:v2:flows:update --sid FW20bcee1211df5e936c014d11519e1aef --status published

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”:

twilio api:studio:v2:flows:revisions:fetch --sid FW20bcee1211df5e936c014d11519e1aef --revision 5 -o json | jq '.[0].definition' > demo.json
twilio api:studio:v2:flows:update --sid FW20bcee1211df5e936c014d11519e1aef --status published --definition "`cat demo.json`"

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.

Test users displayed in Studio 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:

twilio api:studio:v2:flows:test-users:fetch --sid FW20bcee1211df5e936c014d11519e1aef

Update the Test Users of a Flow:

twilio api:studio:v2:flows:test-users:update \
   --sid FW20bcee1211df5e936c014d11519e1aef \
   --test-users +14155551212 +14155551213 zack dave

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!

A note about v1

The v1 REST API for Studio will remain available for use -- we have no plans to deprecate it. However, we will not be updating v1 with new features going forward. Check out the differences between v1 and v2 before migrating.

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