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.
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
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 of any of the Activities in the Workspace.
- If a Reservation times out, the Worker is placed in the
TimeoutActivityidentified by the Workspace. By default this isOffline. - When a new Worker is created, the Worker is placed in the
DefaultActivityidentified by the Workspace, unless a specific ActivitySid is passed. By default, this isOffline.
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 theReservedActivity. - When a Worker accepts a Task, the Worker is placed in the
AssignmentActivityidentified by the TaskQueue that assigns the Worker the Task. By default this is theBusyActivity.
In a multitasking Workspace, a Worker's state does not automatically update when a Task is assigned or accepted.
Activity properties
Pagination is not supported under this resource. Please avoid usage of the page query parameter.
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account that created the Activity resource. |
available
|
Whether the Worker is eligible to receive a Task when it occupies the Activity. A value of |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
friendly_name
|
The string that you assigned to describe the Activity resource. |
sid
|
The unique string that we created to identify the Activity resource. |
workspace_sid
|
The SID of the Workspace that contains the Activity. |
url
|
The absolute URL of the Activity resource. |
links
|
|
Create an Activity resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities
The maximum amount of Activities allowed for any given Workspace is 100.
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace that the new Activity belongs to. |
friendly_name
Required
|
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: |
available
Optional
|
Whether the Worker should be eligible to receive a Task when it occupies the Activity. A value of |
Example 1
Fetch an Activity resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Activity resources to fetch. |
sid
Path
|
The SID of the Activity resource to fetch. |
Example 1
Read multiple Activity resources
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities
By default, this will return the first 50 Activities. Supply a PageSize parameter to fetch more than 50 Activities. See paging for more information.
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Activity resources to read. |
friendly_name
Optional
|
The |
available
Optional
|
Whether return only Activity resources that are available or unavailable. A value of |
Example 1
Update an Activity resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Activity resources to update. |
sid
Path
|
The SID of the Activity resource to update. |
friendly_name
Optional
|
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: |
Example 1
Delete an Activity resource
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
workspace_sid
Path
|
The SID of the Workspace with the Activity resources to delete. |
sid
Path
|
The SID of the Activity resource to delete. |
Example 1
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
