Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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.

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 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.

If a Workspace in which multiple tasks can be assigned to a Worker, a Worker's state does not automatically update when a Task is assigned.

Activity properties

Names in PHP format
accountSid
sid<AC> Not PII

The SID of the Account that created the Activity resource.

available
boolean 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.

dateCreated
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

dateUpdated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

friendlyName
string Not PII

The string that you assigned to describe the Activity resource.

sid
sid<WA> Not PII

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

workspaceSid
sid<WS> Not PII

The SID of the Workspace that contains the Activity.

url
url Not PII

The absolute URL of the Activity resource.

Create an Activity resource

post
https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities

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

Parameters
Names in None format
workspace_sid
Required
post sid<WS> Not PII

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

friendly_name
Required
post string 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.

available
Optional
post boolean 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.

Example 1
        
        
        
        

        Fetch an Activity resource

        get
        https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}
        Parameters
        Names in None format
        workspace_sid
        Required
        get sid<WS> Not PII

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

        sid
        Required
        get sid<WA> Not PII

        The SID of the Activity resource to fetch.

        Example
              
              
              
              

              Read multiple Activity resources

              get
              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
              Names in None format
              workspace_sid
              Required
              get sid<WS> Not PII

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

              friendly_name
              Optional
              get string Not PII

              The friendly_name of the Activity resources to read.

              available
              Optional
              get string 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.

              Example
                    
                    
                    
                    

                    Update an Activity resource

                    post
                    https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}
                    Parameters
                    Names in None format
                    workspace_sid
                    Required
                    post sid<WS> Not PII

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

                    sid
                    Required
                    post sid<WA> Not PII

                    The SID of the Activity resource to update.

                    friendly_name
                    Optional
                    post string 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.

                    Example 1
                          
                          
                          
                          

                          Delete an Activity resource

                          delete
                          https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/Activities/{Sid}
                          Parameters
                          Names in None format
                          workspace_sid
                          Required
                          delete sid<WS> Not PII

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

                          sid
                          Required
                          delete sid<WA> Not PII

                          The SID of the Activity resource to delete.

                          Example
                                
                                
                                
                                
                                Rate this page:

                                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 browsing the Twilio tag on Stack Overflow.