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

Activity Resource

Activities describe the current status of your Workers, which determines whether they are eligible to receive task assignments. Workers are always set to a single Activity.

(information)

Info

TaskRouter pre-populates new Workspaces with "Offline", "Unavailable", and "Available" Activities. Add your own Activities to the list to get a more granular understanding of the way your Workers are spending their time!

Each Activity has:

A FriendlyName, which describes the Worker's state in human-readable terms, and

An Availability, which is a Boolean that determines whether Workers are available for task assignment. The value cannot be changed after the Activity is created.

If a Worker is performing an Activity that has an availability of "true", it means that Worker is ready to have Tasks assigned to it. If a Worker is set to an Activity with an availability of "false", it means the Worker is not able to accept new Tasks and will not be considered for assignment.

By moving Workers from unavailable to available Activities you signal to TaskRouter that the Worker can be assigned new Tasks. When TaskRouter assigns the Worker a Task, it will automatically move the Worker to an unavailable Activity, so that the Worker is not assigned new Tasks while they are occupied. On completion of their work, the Worker can be moved to an available Activity to begin accepting new Tasks again.

Configuring Default Activities for Worker State Transitions

configuring-default-activities-for-worker-state-transitions page anchor

The current Activity for a given Worker is changed in the following operations:

  • Your application can update a Worker's Activity by posting to the Worker instance resource and providing the SID if any of the Activities in the Workspace.
  • If a Reservation times out, the Worker is placed in the TimeoutActivity identified by the Workspace. By default this is Offline.
  • When a new Worker is created, the Worker is placed in the DefaultActivity identified by the Workspace, unless a specific ActivitySid is passed. By default, this is Offline.

In addition, a single-tasking Workspace supports two additional automatic state transitions:

  • When the Worker is assigned a Task, the Worker is placed in the ReservationActivityidentified by the TaskQueue that assigns the Worker the Task. By default this is the Reserved Activity.
  • When a Worker accepts a Task, the Worker is placed in the AssignmentActivity identified by the TaskQueue that assigns the Worker the Task. By default this is the Busy Activity.

In a multitasking Workspace, a Worker's state does not automatically update when a Task is assigned or accepted.

Activity Properties

activity-properties page anchor
(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 Activity resource.

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

Whether the Worker is eligible to receive a Task when it occupies the Activity. A value of true, 1, or yes indicates the Activity is available. All other values indicate that it is not. The value cannot be changed after the Activity is created.

date_createdstring<date-time>Optional
Not PII

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
Not PII

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

friendly_namestringOptional
Not PII

The string that you assigned to describe the Activity resource.

sidSID<WA>Optional
Not PII

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

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

The SID of the Workspace that contains the Activity.

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

The absolute URL of the Activity resource.

linksobject<uri-map>Optional
Not PII

Create an Activity resource

create-an-activity-resource page anchor
POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities

(information)

Info

The maximum amount of Activities allowed for any given Workspace is 100.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace that the new Activity belongs to.

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

Request body parameters

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

A descriptive string that you create to describe the Activity resource. It can be up to 64 characters long. These names are used to calculate and expose statistics about Workers, and provide visibility into the state of each Worker. Examples of friendly names include: on-call, break, and email.

AvailablebooleanOptional
Not PII

Whether the Worker should be eligible to receive a Task when it occupies the Activity. A value of true, 1, or yes specifies the Activity is available. All other values specify that it is not. The value cannot be changed after the Activity is created.

Create a new ActivityLink to code sample: Create a new Activity
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 createActivity() {

11
  const activity = await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .activities.create({

14
      available: true,

15
      friendlyName: "NewAvailableActivity",

16
    });

17


18
  console.log(activity.accountSid);

19
}

20


21
createActivity();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "available": true,

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

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

6
  "friendly_name": "NewAvailableActivity",

7
  "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

8
  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

9
  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

10
  "links": {

11
    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

12
  }

13
}

Fetch an Activity resource

fetch-an-activity-resource page anchor
GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace with the Activity resources to fetch.

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

The SID of the Activity resource to fetch.

Pattern: ^WA[0-9a-fA-F]{32}$Min length: 34Max length: 34
Fetch an ActivityLink to code sample: Fetch an Activity
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 fetchActivity() {

11
  const activity = await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .activities("WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

14
    .fetch();

15


16
  console.log(activity.accountSid);

17
}

18


19
fetchActivity();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "available": true,

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

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

6
  "friendly_name": "New Activity",

7
  "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

8
  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

9
  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

10
  "links": {

11
    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

12
  }

13
}

Read multiple Activity resources

read-multiple-activity-resources page anchor
GET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities

(information)

Info

By default, this will return the first 50 Activities. Supply a PageSize parameter to fetch more than 50 Activities. See paging for more information.

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace with the Activity resources to read.

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

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
FriendlyNamestringOptional
Not PII

The friendly_name of the Activity resources to read.

AvailablestringOptional
Not PII

Whether return only Activity resources that are available or unavailable. A value of true returns only available activities. Values of '1' or yes also indicate true. All other values represent false and return activities that are unavailable.

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 ActivitysLink to code sample: List multiple Activitys
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 listActivity() {

11
  const activities = await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

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

14


15
  activities.forEach((a) => console.log(a.accountSid));

16
}

17


18
listActivity();

Output

1
{

2
  "activities": [

3
    {

4
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
      "available": true,

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

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

8
      "friendly_name": "New Activity",

9
      "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

10
      "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

11
      "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

12
      "links": {

13
        "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

14
      }

15
    }

16
  ],

17
  "meta": {

18
    "first_page_url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities?Available=true&FriendlyName=friendly_name&PageSize=50&Page=0",

19
    "key": "activities",

20
    "next_page_url": null,

21
    "page": 0,

22
    "page_size": 50,

23
    "previous_page_url": null,

24
    "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities?Available=true&FriendlyName=friendly_name&PageSize=50&Page=0"

25
  }

26
}

Update an Activity resource

update-an-activity-resource page anchor
POST https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}

Path parameters

path-parameters-3 page anchor
Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace with the Activity resources to update.

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

The SID of the Activity resource to update.

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

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
FriendlyNamestringOptional
Not PII

A descriptive string that you create to describe the Activity resource. It can be up to 64 characters long. These names are used to calculate and expose statistics about Workers, and provide visibility into the state of each Worker. Examples of friendly names include: on-call, break, and email.

Update an ActivityLink to code sample: Update an Activity
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 updateActivity() {

11
  const activity = await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .activities("WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

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

15


16
  console.log(activity.accountSid);

17
}

18


19
updateActivity();

Output

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "available": true,

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

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

6
  "friendly_name": "another_name",

7
  "sid": "WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

8
  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Activities/WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

9
  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

10
  "links": {

11
    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

12
  }

13
}

Delete an Activity resource

delete-an-activity-resource page anchor
DELETE https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}

Path parameters

path-parameters-4 page anchor
Property nameTypeRequiredPIIDescription
WorkspaceSidSID<WS>required
Not PII

The SID of the Workspace with the Activity resources to delete.

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

The SID of the Activity resource to delete.

Pattern: ^WA[0-9a-fA-F]{32}$Min length: 34Max length: 34
Delete an ActivityLink to code sample: Delete an Activity
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 deleteActivity() {

11
  await client.taskrouter.v1

12
    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .activities("WAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

14
    .remove();

15
}

16


17
deleteActivity();

Need some help?

Terms of service
Privacy Policy

Copyright © 2024 Twilio Inc.