Menu

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?

REST API: Activities

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.

Each Activity has a FriendlyName which describes the Worker's state in human readable terms. Each Activity also has a boolean "availability" value, which determine whether Workers currently occupied by that Activity are available for Task assignment. If a Worker is set to 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.

Default Activities

TaskRouter pre-populates new Workspaces with the Activities "Offline", "Idle", "Busy", and "Reserved" to make it easy to get up and running quickly. You may add your own Activities to this list if you'd like a more granular understanding of the way your Workers are spending their time.

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, providing any of the ActivitySids present 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 ReservationActivity identified 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.

Actions


List All Activities

Resource URI

GET /v1/Workspaces/{WorkspaceSid}/Activities

Returns the list of Activities in the workspace identified by {WorkspaceSid}.

Example

An example that lists all in a workspace

Loading Code Sample...
      
      
      
      

      List Filters

      The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

      Field Description
      FriendlyName Filter by an Activity's friendly name (🏢 not PII )
      Available Filter by activities that are available or unavailable. (Note: This can be 'true', '1'' or 'yes' to indicate a true value. All other values will represent false) (🏢 not PII )

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


      Create an Activity

      Resource URI

      POST /v1/Workspaces/{WorkspaceSid}/Activities
      

      Creates a new Activity.

      Example

      An example for creating a new activity

      Loading Code Sample...
          
          
          
          
          Required Parameters
          Field Description
          FriendlyName A human-readable name for the Activity, such as 'On Call', 'Break', 'Email', etc. Must be unique in this Workspace. These names will be used to calculate and expose statistics about workers, and give you visibility into the state of each of your workers. (🏢 not PII )
          Optional Parameters
          Field Description
          Available Boolean value indicating whether the worker should be eligible to receive a Task when they occupy this Activity. For example, a call center might have an activity named 'On Call' with an availability set to 'false'. Note: This can be 'true', '1' or 'yes' to indicate a true value. All other values will represent false. Defaults to false. (🏢 not PII )

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


          Retrieve an Activity

          Resource URI

          GET /v1/Workspaces/{WorkspaceSid}/Activities/{ActivitySid}
          

          Returns a single Activity resource identified by {ActivitySid}.

          Example

          Example for retrieving a single activity

          Loading Code Sample...
              
              
              
              

              Resource Properties

              Field Description
              Sid The unique ID for this Activity.
              AccountSid The unique ID of the Account that owns this Activity.
              WorkspaceSid The unique ID of the Workspace that this Activity belongs to.
              FriendlyName A human-readable name for the Activity, such as 'on-call', 'break', 'email', etc. These names will be used to calculate and expose statistics about workers, and give you visibility into the state of each of your workers.
              Available Boolean value indicating whether the worker should be eligible to receive a Task when they occupy this Activity. For example, in an activity called 'On Call', the worker would be unavailable to receive additional Task assignments.
              DateCreated The date this Activity was created.
              DateUpdated The date this Activity was updated.

              Update an Activity

              Resource URI

              POST /v1/Workspaces/{WorkspaceSid}/Activities/{ActivitySid}
              

              Updates an Activity identified by {ActivitySid}

              Example

              Example for updating activity FriendlyName

              Loading Code Sample...
                  
                  
                  
                  

                  POST Parameters

                  You may use the following parameters when modifying a Activity resource.

                  Field Description
                  FriendlyName A human-readable name for the Activity, such as 'on-call', 'break', 'email', etc. These names will be used to calculate and expose statistics about workers, and give you visibility into the state of each of your workers. (🏢 not PII )

                  Delete an Activity

                  Resource URI

                  DELETE /v1/Workspaces/{WorkspaceSid}/Activities/{ActivitySid}
                  

                  Deletes the Activity identified by {ActivitySid}. This will fail if any Workers currently occupy that Activity.

                  Example

                  Example for deleting an activity

                  Loading Code Sample...
                      
                      
                      
                      

                      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.

                      Loading Code Sample...