Skip to content Skip to navigation Skip to topbar

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 nameTypeRequiredDescriptionChild properties

sidSID<FW>

Optional

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>

Optional

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

Optional

Not PII

The string that you assigned to describe the Flow.

definitionobject

Optional

Not PII

JSON representation of flow definition.

statusenum<string>

Optional

Not PII

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

Possible values:

draftpublished

revisioninteger

Optional

Not PII

The latest revision number of the Flow's definition.

Default: 0

commit_messagestring

Optional

Not PII

Description of change made in the revision.

validboolean

Optional

Not PII

Boolean if the flow definition is valid.

errorsarray[object]

Optional

Not PII

List of error in the flow definition.

warningsarray[object]

Optional

Not PII

List of warnings in the flow definition.

date_createdstring<date-time>

Optional

Not PII

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

date_updatedstring<date-time>

Optional

Not PII

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

webhook_urlstring<uri>

Optional

Not PII

urlstring<uri>

Optional

Not PII

The absolute URL of the resource.

linksobject<uri-map>

Optional

Not PII

The URLs of the Flow's nested resources.

Create a Flow resource

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

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.

CommitMessagestring

Optional

Not PII

Description of change made in the revision.

Create Flow

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createFlow() {
11  const flow = await client.studio.v2.flows.create({
12    commitMessage: "First draft",
13    definition: {
14      description: "A New Flow",
15      states: [
16        {
17          name: "Trigger",
18          type: "trigger",
19          transitions: [],
20          properties: {
21            offset: {
22              x: 0,
23              y: 0,
24            },
25          },
26        },
27      ],
28      initial_state: "Trigger",
29      flags: {
30        allow_concurrent_calls: true,
31      },
32    },
33    friendlyName: "Main IVR",
34    status: "draft",
35  });
36
37  console.log(flow.sid);
38}
39
40createFlow();

Output

1{
2  "sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "definition": {
5    "initial_state": "Trigger"
6  },
7  "friendly_name": "Main IVR",
8  "status": "draft",
9  "revision": 1,
10  "commit_message": "First draft",
11  "valid": true,
12  "errors": [],
13  "warnings": [],
14  "webhook_url": "http://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "date_created": "2017-11-06T12:00:00Z",
16  "date_updated": null,
17  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "links": {
19    "test_users": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TestUsers",
20    "revisions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Revisions",
21    "executions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions"
22  }
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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchFlow() {
11  const flow = await client.studio.v2
12    .flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .fetch();
14
15  console.log(flow.sid);
16}
17
18fetchFlow();

Output

1{
2  "sid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "friendly_name": "Test Flow",
5  "definition": {
6    "initial_state": "Trigger"
7  },
8  "status": "published",
9  "revision": 1,
10  "commit_message": "commit",
11  "valid": true,
12  "errors": [],
13  "warnings": [],
14  "webhook_url": "http://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "date_created": "2017-11-06T12:00:00Z",
16  "date_updated": null,
17  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "links": {
19    "test_users": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TestUsers",
20    "revisions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Revisions",
21    "executions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions"
22  }
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

PageSizeinteger<int64>

Optional

Not PII

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

Not PII

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

Minimum: 0

PageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Read Flows

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listFlow() {
11  const flows = await client.studio.v2.flows.list({ limit: 20 });
12
13  flows.forEach((f) => console.log(f.sid));
14}
15
16listFlow();

Output

1{
2  "meta": {
3    "previous_page_url": null,
4    "next_page_url": null,
5    "url": "https://studio.twilio.com/v2/Flows?PageSize=50&Page=0",
6    "page": 0,
7    "first_page_url": "https://studio.twilio.com/v2/Flows?PageSize=50&Page=0",
8    "page_size": 50,
9    "key": "flows"
10  },
11  "flows": [
12    {
13      "sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "friendly_name": "Test Flow",
16      "status": "published",
17      "revision": 1,
18      "definition": null,
19      "commit_message": null,
20      "valid": null,
21      "errors": null,
22      "warnings": null,
23      "webhook_url": "http://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24      "date_created": "2017-11-06T12:00:00Z",
25      "date_updated": "2017-11-06T12:00:00Z",
26      "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27      "links": {
28        "test_users": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TestUsers",
29        "revisions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Revisions",
30        "executions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions"
31      }
32    }
33  ]
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

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Statusenum<string>required

Not PII

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

Possible values:

draftpublished

FriendlyNamestring

Optional

Not PII

The string that you assigned to describe the Flow.

Definitionobject

Optional

Not PII

JSON representation of flow definition.

CommitMessagestring

Optional

Not PII

Description of change made in the revision.

Update Flow

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateFlow() {
11  const flow = await client.studio.v2
12    .flows("FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .update({
14      commitMessage: "Prod release v2",
15      definition: {
16        description: "A New Flow",
17        states: [
18          {
19            name: "Trigger",
20            type: "trigger",
21            transitions: [
22              {
23                event: "incomingMessage",
24              },
25              {
26                next: "say_play_1",
27                event: "incomingCall",
28              },
29              {
30                event: "incomingRequest",
31              },
32            ],
33            properties: {
34              offset: {
35                x: 0,
36                y: 0,
37              },
38            },
39          },
40          {
41            name: "say_play_1",
42            type: "say-play",
43            transitions: [
44              {
45                event: "audioComplete",
46              },
47            ],
48            properties: {
49              offset: {
50                x: 173,
51                y: 212,
52              },
53              loop: 1,
54              say: "Hello world",
55            },
56          },
57        ],
58        initial_state: "Trigger",
59        flags: {
60          allow_concurrent_calls: true,
61        },
62      },
63      status: "published",
64    });
65
66  console.log(flow.sid);
67}
68
69updateFlow();

Output

1{
2  "sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "definition": {
5    "initial_state": "Trigger"
6  },
7  "friendly_name": "Test Flow",
8  "status": "published",
9  "revision": 1,
10  "commit_message": "Prod release v2",
11  "valid": true,
12  "errors": [],
13  "warnings": [],
14  "webhook_url": "http://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "date_created": "2017-11-06T12:00:00Z",
16  "date_updated": "2017-11-06T12:00:00Z",
17  "url": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "links": {
19    "test_users": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TestUsers",
20    "revisions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Revisions",
21    "executions": "https://studio.twilio.com/v2/Flows/FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Executions"
22  }
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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteFlow() {
11  await client.studio.v2.flows("FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
12}
13
14deleteFlow();