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.


Property nameTypeRequiredDescriptionChild properties
sidSID<FW>

Optional

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_namestring

Optional

The string that you assigned to describe the Flow.


definitionobject

Optional

JSON representation of flow definition.


statusenum<string>

Optional

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

Possible values:
draftpublished

revisioninteger

Optional

The latest revision number of the Flow's definition.

Default: 0

commit_messagestring

Optional

Description of change made in the revision.


validboolean

Optional

Boolean if the flow definition is valid.


errorsarray[object]

Optional

List of error in the flow definition.


warningsarray[object]

Optional

List of warnings in the flow definition.


date_createdstring<date-time>

Optional

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


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

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.


CommitMessagestring

Optional

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 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
PageSizeinteger<int64>

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

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

FriendlyNamestring

Optional

The string that you assigned to describe the Flow.


Definitionobject

Optional

JSON representation of flow definition.


CommitMessagestring

Optional

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();