Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Workflow Resource

Workflows control how tasks will be prioritized and routed into Queues, and how Tasks should escalate in priority or move across queues over time. Workflows are described in a simple JSON format and can be modified through the REST API or through the account portal. You can learn more about Workflows here.

You specify which Workflow should control a Task when you add the Task to the Workspace. The Workflow will manage the Task's queue and priority until it is either assigned to a Worker, removed from the queue, or modified.

When a Task is assigned to a Worker, your application will receive a callback to the Workflow's AssignmentCallbackUrl, and your application can then do whatever is required to deliver the Task to the worker (for example, instructing Twilio to dial the phone number of the Worker selected to receive the call). Read more about Task assignment here.

Multiple Workflows

A Workspace can contain multiple Workflows. This allows you to have different sets of routing rules for different types of applications or situations.

For example, a call center has one group of Workers that handles both phone and chat tasks. These two Task types have different service-level targets and agent requirements. They will also originate from separate external applications. To separate application concerns, the call center creates a single Workspace with two separate Workflows, one for phone calls and the other for chat requests.

Creating and Distributing Tasks

Whenever you add a Task to a Workspace you indicate which Workflow should route the Task. The Workflow will prioritize the task and place it into a queue, where it will be distributed to the first available Worker that has the necessary capabilities. See the Task Resource for more information.

Handling Task Assignments with the AssignmentCallbackUrl

Every Workflow has an AssignmentCallbackURL property, as well as a FallbackAssignmentCallbackUrl in case requests to the first URL fail. When a Worker is assigned a Task, TaskRouter will make an HTTP request to this URL. Your application must handle this request to then do whatever is required to connect the Task to the Worker in your application. For example, this might mean pushing a case to an instance of an agent's web application, or dialing an agent's phone number using Twilio. See this section for more information on handling Task Assignment callbacks.

(information)

Info

The AssignmentCallbackUrl is not required if you are planning on using just the JS SDK. In that case, simply leave the value blank.

If we cannot hit your AssignmentCallbackUrl or FallbackAssignmentCallbackUrl, TaskRouter will automatically change your Reservation status to canceled. To get a better sense of how assignment callbacks work, use a tool like Beeceptor to ensure that the assignment callback is firing correctly and to examine the contents of the post.

Workflow Properties

(warning)

Warning

Pagination is not supported under this resource. Please avoid usage of the page query parameter.

Property nameTypeRequiredDescriptionChild properties
account_sidSID<AC>Optional
Not PII

The SID of the Account that created the Workflow resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
assignment_callback_urlstring<uri>Optional
Not PII

The URL that we call when a task managed by the Workflow is assigned to a Worker. See Assignment Callback URL for more information.

configurationstringOptional
Not PII

A JSON string that contains the Workflow's configuration. See Configuring Workflows for more information.

date_createdstring<date-time>Optional
Not PII

The date and time in GMT when the resource was created specified in RFC 2822 format.

date_updatedstring<date-time>Optional
Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

document_content_typestringOptional
Not PII

The MIME type of the document.

fallback_assignment_callback_urlstring<uri>Optional
Not PII

The URL that we call when a call to the assignment_callback_url fails.

friendly_namestringOptional
PII MTL: 30 days

The string that you assigned to describe the Workflow resource. For example, Customer Support or 2014 Election Campaign.

sidSID<WW>Optional
Not PII

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

Pattern: ^WW[0-9a-fA-F]{32}$Min length: 34Max length: 34
task_reservation_timeoutintegerOptional
Not PII

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.

Default: 0
workspace_sidSID<WS>Optional
Not PII

The SID of the Workspace that contains the Workflow.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34
urlstring<uri>Optional
Not PII

The absolute URL of the Workflow resource.

linksobject<uri-map>Optional
Not PII

The URLs of related resources.

Create a Workflow resource

POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows

Path parameters

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace that the new Workflow to create belongs to.

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

Request body parameters

Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
FriendlyNamestringrequired
PII MTL: 30 days

A descriptive string that you create to describe the Workflow resource. For example, Inbound Call Workflow or 2014 Outbound Campaign.

Configurationstringrequired
Not PII

A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows for more information.

AssignmentCallbackUrlstring<uri>Optional
Not PII

The URL from your application that will process task assignment events. See Handling Task Assignment Callback for more details.

FallbackAssignmentCallbackUrlstring<uri>Optional
Not PII

The URL that we should call when a call to the assignment_callback_url fails.

TaskReservationTimeoutintegerOptional
Not PII

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.

Create a Workflow
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 createWorkflow() {

11
  const workflow = await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .workflows.create({

14
      assignmentCallbackUrl: "https://example.com/",

15
      configuration: JSON.stringify({

16
        task_routing: {

17
          filters: [

18
            {

19
              expression: "type=='sales'",

20
              targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],

21
            },

22
            {

23
              expression: "type=='marketing'",

24
              targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],

25
            },

26
            {

27
              expression: "type=='support'",

28
              targets: [{ queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }],

29
            },

30
          ],

31
          default_filter: { queue: "WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" },

32
        },

33
      }),

34
      fallbackAssignmentCallbackUrl: "https://example2.com/",

35
      friendlyName: "Sales, Marketing, Support Workflow",

36
    });

37


38
  console.log(workflow.accountSid);

39
}

40


41
createWorkflow();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "assignment_callback_url": "https://example.com/",

4
  "configuration": "{\"task_routing\": {\"filters\": [{\"expression\": \"type=='sales'\", \"targets\": [{\"queue\": \"WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}]}, {\"expression\": \"type=='marketing'\", \"targets\": [{\"queue\": \"WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}]}, {\"expression\": \"type=='support'\", \"targets\": [{\"queue\": \"WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}]}], \"default_filter\": {\"queue\": \"WQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"}}}",

5
  "date_created": "2014-05-14T10:50:02Z",

6
  "date_updated": "2014-05-14T23:26:06Z",

7
  "document_content_type": "application/json",

8
  "fallback_assignment_callback_url": "https://example2.com/",

9
  "friendly_name": "Sales, Marketing, Support Workflow",

10
  "sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

11
  "task_reservation_timeout": 120,

12
  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

13
  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

14
  "links": {

15
    "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",

16
    "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics",

17
    "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics"

18
  }

19
}

Fetch a Workflow resource

GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace with the Workflow to fetch.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34
SidSID<WW>required
Not PII

The SID of the Workflow resource to fetch.

Pattern: ^WW[0-9a-fA-F]{32}$Min length: 34Max length: 34
Fetch a Workflow
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 fetchWorkflow() {

11
  const workflow = await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

14
    .fetch();

15


16
  console.log(workflow.accountSid);

17
}

18


19
fetchWorkflow();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "assignment_callback_url": "http://example.com",

4
  "configuration": "task-routing:\\n  - filter: \\n      - 1 == 1\\n    target:\\n      - queue: WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\\n        set-priority: 0\\n",

5
  "date_created": "2014-05-14T10:50:02Z",

6
  "date_updated": "2014-05-14T23:26:06Z",

7
  "document_content_type": "application/json",

8
  "fallback_assignment_callback_url": null,

9
  "friendly_name": "Default Fifo Workflow",

10
  "sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

11
  "task_reservation_timeout": 120,

12
  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

13
  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

14
  "links": {

15
    "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",

16
    "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics",

17
    "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics"

18
  }

19
}

Read multiple Workflow resources

GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows

Path parameters

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace with the Workflow to read.

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

Query parameters

Property nameTypeRequiredPIIDescription
FriendlyNamestringOptional
PII MTL: 30 days

The friendly_name of the Workflow resources to read.

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.

List multiple Workflows
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 listWorkflow() {

11
  const workflows = await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .workflows.list({ limit: 20 });

14


15
  workflows.forEach((w) => console.log(w.accountSid));

16
}

17


18
listWorkflow();

Output

1
{

2
  "meta": {

3
    "first_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows?FriendlyName=friendly_name&PageSize=50&Page=0",

4
    "key": "workflows",

5
    "next_page_url": null,

6
    "page": 0,

7
    "page_size": 50,

8
    "previous_page_url": null,

9
    "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows?FriendlyName=friendly_name&PageSize=50&Page=0"

10
  },

11
  "workflows": [

12
    {

13
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

14
      "assignment_callback_url": "http://example.com",

15
      "configuration": "task-routing:\\n  - filter: \\n      - 1 == 1\\n    target:\\n      - queue: WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\\n        set-priority: 0\\n",

16
      "date_created": "2014-05-14T10:50:02Z",

17
      "date_updated": "2014-05-15T16:47:51Z",

18
      "document_content_type": "application/json",

19
      "fallback_assignment_callback_url": null,

20
      "friendly_name": "Default Fifo Workflow",

21
      "sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

22
      "task_reservation_timeout": 120,

23
      "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

24
      "links": {

25
        "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",

26
        "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics",

27
        "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics"

28
      },

29
      "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

30
    }

31
  ]

32
}

Update a Workflow resource

POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}

Modifies a Workflow. Whenever you modify a workflow, the following will take place:

  • TaskRouter validates your Workflow configuration to ensure it is syntactically correct and that all queues referenced in the document exist. If any problems are found, the update will fail, and the active Workflow will remain in place.
  • Assuming there are no problems with the configuration provided, TaskRouter will use the previous Workflow to route any Tasks that were pending prior to the change. New Tasks will begin using the updated Workflow immediately.

Path parameters

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace with the Workflow to update.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34
SidSID<WW>required
Not PII

The SID of the Workflow resource to update.

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

Request body parameters

Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
FriendlyNamestringOptional
PII MTL: 30 days

A descriptive string that you create to describe the Workflow resource. For example, Inbound Call Workflow or 2014 Outbound Campaign.

AssignmentCallbackUrlstring<uri>Optional
Not PII

The URL from your application that will process task assignment events. See Handling Task Assignment Callback for more details.

FallbackAssignmentCallbackUrlstring<uri>Optional
Not PII

The URL that we should call when a call to the assignment_callback_url fails.

ConfigurationstringOptional
Not PII

A JSON string that contains the rules to apply to the Workflow. See Configuring Workflows for more information.

TaskReservationTimeoutintegerOptional
Not PII

How long TaskRouter will wait for a confirmation response from your application after it assigns a Task to a Worker. Can be up to 86,400 (24 hours) and the default is 120.

ReEvaluateTasksstringOptional
Not PII

Whether or not to re-evaluate Tasks. The default is false, which means Tasks in the Workflow will not be processed through the assignment loop again.

Update a Workflow
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 updateWorkflow() {

11
  const workflow = await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

14
    .update({ friendlyName: "FriendlyName" });

15


16
  console.log(workflow.accountSid);

17
}

18


19
updateWorkflow();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "assignment_callback_url": "http://example.com",

4
  "configuration": "task-routing:\\n  - filter: \\n      - 1 == 1\\n    target:\\n      - queue: WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\\n        set-priority: 0\\n",

5
  "date_created": "2014-05-14T10:50:02Z",

6
  "date_updated": "2014-05-14T23:26:06Z",

7
  "document_content_type": "application/json",

8
  "fallback_assignment_callback_url": null,

9
  "friendly_name": "FriendlyName",

10
  "sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

11
  "task_reservation_timeout": 120,

12
  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

13
  "links": {

14
    "statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Statistics",

15
    "real_time_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RealTimeStatistics",

16
    "cumulative_statistics": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/CumulativeStatistics"

17
  },

18
  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

19
}

Delete a Workflow resource

DELETE https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Workflows/{Sid}

Deletes a Workflow. Will return an error if there are any pending or reserved Tasks still being controlled by this Workflow.

Path parameters

Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace with the Workflow to delete.

Pattern: ^WS[0-9a-fA-F]{32}$Min length: 34Max length: 34
SidSID<WW>required
Not PII

The SID of the Workflow resource to delete.

Pattern: ^WW[0-9a-fA-F]{32}$Min length: 34Max length: 34
Delete a Workflow
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 deleteWorkflow() {

11
  await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .workflows("WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

14
    .remove();

15
}

16


17
deleteWorkflow();