Skip to contentSkip to navigationSkip 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

flow-properties page anchor
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

The SID of the Account that created the Flow resource.

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

friendly_namestringOptional

The string that you assigned to describe the Flow.


definitionobjectOptional

JSON representation of flow definition.


statusenum<string>Optional

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

Possible values:
draftpublished

revisionintegerOptional

The latest revision number of the Flow's definition.

Default: 0

commit_messagestringOptional

Description of change made in the revision.


validbooleanOptional

Boolean if the flow definition is valid.


errorsarrayOptional

List of error in the flow definition.


warningsarrayOptional

List of warnings in the flow definition.


date_updatedstring<date-time>Optional

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


webhook_urlstring<uri>Optional

urlstring<uri>Optional

The absolute URL of the resource.


linksobject<uri-map>Optional

The URLs of the Flow's nested resources.


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

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
FriendlyNamestringrequired

The string that you assigned to describe the Flow.


Statusenum<string>required

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

Possible values:
draftpublished

Definitionobjectrequired

JSON representation of flow definition.


CommitMessagestringOptional

Description of change made in the revision.

Create FlowLink to code sample: Create Flow
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async 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
40
createFlow();

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
}

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

Property nameTypeRequiredPIIDescription
SidSID<FW>required

The SID of the Flow resource to fetch.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchFlow() {
11
const flow = await client.studio.v2
12
.flows("FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
.fetch();
14
15
console.log(flow.sid);
16
}
17
18
fetchFlow();

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

read-multiple-flow-resources page anchor
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.

Property nameTypeRequiredPIIDescription
PageSizeintegerOptional

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

Minimum: 1Maximum: 1000

PageintegerOptional

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

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listFlow() {
11
const flows = await client.studio.v2.flows.list({ limit: 20 });
12
13
flows.forEach((f) => console.log(f.sid));
14
}
15
16
listFlow();

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
}

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

Property nameTypeRequiredPIIDescription
SidSID<FW>required

The SID of the Flow resource to fetch.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
Statusenum<string>required

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

Possible values:
draftpublished

FriendlyNamestringOptional

The string that you assigned to describe the Flow.


DefinitionobjectOptional

JSON representation of flow definition.


CommitMessagestringOptional

Description of change made in the revision.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async 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
69
updateFlow();

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 https://studio.twilio.com/v2/Flows/{Sid}

Property nameTypeRequiredPIIDescription
SidSID<FW>required

The SID of the Flow resource to delete.

Pattern: ^FW[0-9a-fA-F]{32}$Min length: 34Max length: 34
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function deleteFlow() {
11
await client.studio.v2.flows("FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
12
}
13
14
deleteFlow();