On this page

Flow

Flows are individual workflows that you create. Flow definitions are expressed as instances of a JSON schema.

(information)

Info

Note: Flow definitions are null in the Flows List Resource. To retrieve the Flow definition, use the Fetch method.

Flow Properties

Property nameTypePIIDescription

sidSID<FW>

Not PII

The unique string that we created to identify the Flow resource.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34

account_sidSID<AC>

Not PII

The SID of the Account that created the Flow resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

friendly_namestring

Not PII

The string that you assigned to describe the Flow.

definitionobject

Not PII

JSON representation of flow definition.

statusenum<string>

Not PII

The status of the Flow. Can be: draft or published.

Possible values:

draftpublished

revisioninteger

Not PII

The latest revision number of the Flow's definition.

commit_messagestring

Not PII

Description of change made in the revision.

validboolean

Not PII

Boolean if the flow definition is valid.

errorsarray

Not PII

List of error in the flow definition.

warningsarray

Not PII

List of warnings in the flow definition.

date_createdstring<date-time>

Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updatedstring<date-time>

Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

webhook_urlstring<uri>

Not PII

urlstring<uri>

Not PII

The absolute URL of the resource.

linksobject<uri-map>

Not PII

The URLs of the Flow's nested resources.

Create a Flow resource

POST https://studio.twilio.com/v2/Flows

Request body parameters

Property nameTypeRequiredPIIDescription

FriendlyNamestringrequired

Not PII

The string that you assigned to describe the Flow.

Statusenum<string>required

Not PII

The status of the Flow. Can be: draft or published.

Possible values:

draftpublished

Definitionobjectrequired

Not PII

JSON representation of flow definition.

CommitMessagestringOptional

Not PII

Description of change made in the revision.

Create Flow

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_40// Download the helper library from https://www.twilio.com/docs/node/install
_40const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_40
_40// Find your Account SID and Auth Token at twilio.com/console
_40// and set the environment variables. See http://twil.io/secure
_40const accountSid = process.env.TWILIO_ACCOUNT_SID;
_40const authToken = process.env.TWILIO_AUTH_TOKEN;
_40const client = twilio(accountSid, authToken);
_40
_40async function createFlow() {
_40  const flow = await client.studio.v2.flows.create({
_40    commitMessage: "First draft",
_40    definition: {
_40      description: "A New Flow",
_40      states: [
_40        {
_40          name: "Trigger",
_40          type: "trigger",
_40          transitions: [],
_40          properties: {
_40            offset: {
_40              x: 0,
_40              y: 0,
_40            },
_40          },
_40        },
_40      ],
_40      initial_state: "Trigger",
_40      flags: {
_40        allow_concurrent_calls: true,
_40      },
_40    },
_40    friendlyName: "Main IVR",
_40    status: "draft",
_40  });
_40
_40  console.log(flow.sid);
_40}
_40
_40createFlow();

Output


_23{
_23  "sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "definition": {
_23    "initial_state": "Trigger"
_23  },
_23  "friendly_name": "Main IVR",
_23  "status": "draft",
_23  "revision": 1,
_23  "commit_message": "First draft",
_23  "valid": true,
_23  "errors": [],
_23  "warnings": [],
_23  "webhook_url": "http://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "date_created": "2017-11-06T12:00:00Z",
_23  "date_updated": null,
_23  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "links": {
_23    "test_users": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TestUsers",
_23    "revisions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Revisions",
_23    "executions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions"
_23  }
_23}

Fetch a Flow resource

GET https://studio.twilio.com/v2/Flows/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<FW>required

Not PII

The SID of the Flow resource to fetch.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34

Fetch Flow

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function fetchFlow() {
_18  const flow = await client.studio.v2
_18    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
_18    .fetch();
_18
_18  console.log(flow.sid);
_18}
_18
_18fetchFlow();

Output


_23{
_23  "sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "friendly_name": "Test Flow",
_23  "definition": {
_23    "initial_state": "Trigger"
_23  },
_23  "status": "published",
_23  "revision": 1,
_23  "commit_message": "commit",
_23  "valid": true,
_23  "errors": [],
_23  "warnings": [],
_23  "webhook_url": "http://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "date_created": "2017-11-06T12:00:00Z",
_23  "date_updated": null,
_23  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "links": {
_23    "test_users": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TestUsers",
_23    "revisions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Revisions",
_23    "executions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions"
_23  }
_23}

Read multiple Flow resources

GET https://studio.twilio.com/v2/Flows

(information)

Info

Note: Flow definitions are null in the Flows List Resource. To retrieve the Flow definition, use the Fetch method.

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeintegerOptional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageintegerOptional

Not PII

The page index. This value is simply for client state.

Minimum: 0

PageTokenstringOptional

Not PII

The page token. This is provided by the API.

Read Flows

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function listFlow() {
_16  const flows = await client.studio.v2.flows.list({ limit: 20 });
_16
_16  flows.forEach((f) => console.log(f.sid));
_16}
_16
_16listFlow();

Output


_34{
_34  "meta": {
_34    "previous_page_url": null,
_34    "next_page_url": null,
_34    "url": "https://studio.twilio.com/v2/Flows?PageSize=50&Page=0",
_34    "page": 0,
_34    "first_page_url": "https://studio.twilio.com/v2/Flows?PageSize=50&Page=0",
_34    "page_size": 50,
_34    "key": "flows"
_34  },
_34  "flows": [
_34    {
_34      "sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_34      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_34      "friendly_name": "Test Flow",
_34      "status": "published",
_34      "revision": 1,
_34      "definition": null,
_34      "commit_message": null,
_34      "valid": null,
_34      "errors": null,
_34      "warnings": null,
_34      "webhook_url": "http://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_34      "date_created": "2017-11-06T12:00:00Z",
_34      "date_updated": "2017-11-06T12:00:00Z",
_34      "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_34      "links": {
_34        "test_users": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TestUsers",
_34        "revisions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Revisions",
_34        "executions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions"
_34      }
_34    }
_34  ]
_34}

Update a Flow resource

POST https://studio.twilio.com/v2/Flows/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<FW>required

Not PII

The SID of the Flow resource to fetch.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Property nameTypeRequiredPIIDescription

Statusenum<string>required

Not PII

The status of the Flow. Can be: draft or published.

Possible values:

draftpublished

FriendlyNamestringOptional

Not PII

The string that you assigned to describe the Flow.

DefinitionobjectOptional

Not PII

JSON representation of flow definition.

CommitMessagestringOptional

Not PII

Description of change made in the revision.

Update Flow

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_69// Download the helper library from https://www.twilio.com/docs/node/install
_69const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_69
_69// Find your Account SID and Auth Token at twilio.com/console
_69// and set the environment variables. See http://twil.io/secure
_69const accountSid = process.env.TWILIO_ACCOUNT_SID;
_69const authToken = process.env.TWILIO_AUTH_TOKEN;
_69const client = twilio(accountSid, authToken);
_69
_69async function updateFlow() {
_69  const flow = await client.studio.v2
_69    .flows("FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_69    .update({
_69      commitMessage: "Prod release v2",
_69      definition: {
_69        description: "A New Flow",
_69        states: [
_69          {
_69            name: "Trigger",
_69            type: "trigger",
_69            transitions: [
_69              {
_69                event: "incomingMessage",
_69              },
_69              {
_69                next: "say_play_1",
_69                event: "incomingCall",
_69              },
_69              {
_69                event: "incomingRequest",
_69              },
_69            ],
_69            properties: {
_69              offset: {
_69                x: 0,
_69                y: 0,
_69              },
_69            },
_69          },
_69          {
_69            name: "say_play_1",
_69            type: "say-play",
_69            transitions: [
_69              {
_69                event: "audioComplete",
_69              },
_69            ],
_69            properties: {
_69              offset: {
_69                x: 173,
_69                y: 212,
_69              },
_69              loop: 1,
_69              say: "Hello world",
_69            },
_69          },
_69        ],
_69        initial_state: "Trigger",
_69        flags: {
_69          allow_concurrent_calls: true,
_69        },
_69      },
_69      status: "published",
_69    });
_69
_69  console.log(flow.sid);
_69}
_69
_69updateFlow();

Output


_23{
_23  "sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "definition": {
_23    "initial_state": "Trigger"
_23  },
_23  "friendly_name": "Test Flow",
_23  "status": "published",
_23  "revision": 1,
_23  "commit_message": "Prod release v2",
_23  "valid": true,
_23  "errors": [],
_23  "warnings": [],
_23  "webhook_url": "http://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "date_created": "2017-11-06T12:00:00Z",
_23  "date_updated": "2017-11-06T12:00:00Z",
_23  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "links": {
_23    "test_users": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TestUsers",
_23    "revisions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Revisions",
_23    "executions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions"
_23  }
_23}

Delete a Flow resource

DELETE https://studio.twilio.com/v2/Flows/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<FW>required

Not PII

The SID of the Flow resource to delete.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34

Delete Flow

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_14// Download the helper library from https://www.twilio.com/docs/node/install
_14const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_14
_14// Find your Account SID and Auth Token at twilio.com/console
_14// and set the environment variables. See http://twil.io/secure
_14const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14const authToken = process.env.TWILIO_AUTH_TOKEN;
_14const client = twilio(accountSid, authToken);
_14
_14async function deleteFlow() {
_14  await client.studio.v2.flows("FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
_14}
_14
_14deleteFlow();