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: Workspaces

A Workspace is a container for your Tasks, Workers, TaskQueues, Workflows and Activities. Each of these items exists within a single Workspace and will not be shared across Workspaces. For example, if you were using TaskRouter to distribute tasks for two separate organizations in your business, you might create a Workspace for each organization.

A single Workspace can hold a variety of task types and priorities, and workers with a variety of capabilities. For example, a contact center might collect waiting phone calls, pending cases, and incoming chat requests into a single Workspace. Some of the phone calls in the Workspace might require an agent who speaks English, while others require an agent who speaks Spanish. Some of the tasks might originate from high-value customers, giving them a higher priority, while other tasks can wait longer before resolution.

Actions


List all Workflows

Resource URI

GET /v1/Workspaces

Returns a list of Workspaces for the account {AccountSid}.

Example

Example for listing all workspaces for an account.

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 a workspace’s friendly name. This is a human readable description of this Workspace (for example “Customer Support” or “2014 Election Campaign”)

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


      Create a Workspace

      Resource URI

      POST /v1/Workspaces
      

      Creates a new Workspace.

      Example

      Example for creating a new workspace.

      Loading Code Sample...
          
          
          
          
          Required Parameters
          Field Description
          FriendlyName Human readable description of this workspace (for example “Customer Support” or “2014 Election Campaign”) (📇 PII )
          Optional Parameters
          Field Description
          EventCallbackUrl If provided, the Workspace will publish events to this URL. You can use this to gather data for reporting. See Workspace Events for more information. (🏢 not PII )
          EventsFilter Use this parameter to receive webhooks on EventCallbackUrl for specific events on a workspace. For example if 'EventsFilter=task.created,task.canceled,worker.activity.update', then TaskRouter will webhook to EventCallbackUrl only when a task is created, canceled or a worker activity is updated. (🏢 not PII )
          Template One of the available template names. Will pre-configure this Workspace with the Workflow and Activities specified in the template. “NONE” will create a Workspace with a set of default activities and nothing else. "FIFO" will configure TaskRouter with a set of default activities and a single task queue for first-in, first-out distribution, useful if you want to see a simple TaskRouter configuration when getting started. Defaults to "NONE". (🏢 not PII )
          MultiTaskEnabled Multi tasking allows workers to handle multiple tasks simultaneously. Default is enabled (MultiTaskEnabled=true), where each worker will be eligible to receive parallel reservations up to the per-channel maximums defined in the Workers section. When disabled (MultiTaskEnabled=false), each worker will only receive a new reservation when the previous task is completed. Learn more by visiting Multitasking. (🏢 not PII )
          PrioritizeQueueOrder Use this parameter to configure whether to prioritize LIFO or FIFO when workers are receiving Tasks from combination of LIFO and FIFO TaskQueues. Default is FIFO. Click here to learn more about LIFO and the use of the parameter. (🏢 not PII )

          Note: The maximum amount of Workspaces allowed for any given Account is 5,000. Please contact us if your use case will require more.


          Retrieve a Workspace

          Resource URI

          GET /v1/Workspaces/{WorkspaceSid}
          

          Returns a single Workspace resource identified by {WorkspaceSid}.

          Resource Properties

          A Workspace instance resource is represented by the following properties.

          Example

          Example for retrieving a single Workspace for an account.

          Loading Code Sample...
              
              
              
              
              Field Description
              Sid The unique ID of the Workspace
              AccountSid The ID of the account that owns this Workflow
              FriendlyName Human readable description of this workspace (for example “Sales Call Center” or “Customer Support Team”)
              DefaultActivitySid The ID of the Activity that will be used when new Workers are created in this Workspace.
              DefaultActivityName The human readable name of the default activity. Read only.
              TimeoutActivitySid The ID of the Activity that will be assigned to a Worker when a Task reservation times out without a response.
              TimeoutActivityName The human readable name of the timeout activity. Read only.
              EventCallbackUrl An optional URL where the Workspace will publish events. You can use this to gather data for reporting. See Workspace Events for more information. Optional.
              MultiTaskEnabled Attribute returns true when Multi tasking is enabled and false otherwise. Learn more by visiting Multitasking.
              PrioritizeQueueOrder The current priority for Queue order when workers are receiving Tasks from combination of LIFO and FIFO TaskQueues. Click here to learn more about LIFO.
              DateCreated The time the Workspace was created, given as GMT in ISO 8601 format.
              DateUpdated The time the Workspace was last updated, given as GMT in ISO 8601 format.

              Update a Workspace

              Resource URI

              POST /v1/Workspaces/{WorkspaceSid}
              

              Updates a Workspace.

              Example

              Example for updating a workspace.

              Loading Code Sample...
                  
                  
                  
                  

                  POST Parameters

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

                  Field Description
                  FriendlyName Human readable description of this workspace (for example “Sales Call Center” or “Customer Support Team”) (📇 PII )
                  EventCallbackUrl The Workspace will publish events to this URL. You can use this to gather data for reporting. See Events for more information. (🏢 not PII )
                  EventsFilter Use this parameter to receive webhooks on EventCallbackUrl for specific events on a workspace. For example if 'EventsFilter=task.created,task.canceled,worker.activity.update', then TaskRouter will webhook to EventCallbackUrl only when a task is created, canceled or a worker activity is updated. (🏢 not PII )
                  DefaultActivitySid The ID of the Activity that will be used when new Workers are created in this Workspace. (🏢 not PII )
                  TimeoutActivitySid The ID of the Activity that will be assigned to a Worker when a Task reservation times out without a response. (🏢 not PII )
                  MultiTaskEnabled Enable or Disable Multitasking by passing either true or False with the POST request. Learn more by visiting Multitasking. (🏢 not PII )
                  PrioritizeQueueOrder Use this parameter to configure whether to prioritize LIFO or FIFO when workers are receiving Tasks from combination of LIFO and FIFO TaskQueues. Default is FIFO. Click here to learn more about LIFO and the use of the parameter. (🏢 not PII )

                  Delete a Workspace

                  Resource URI

                  DELETE /v1/Workspaces/{WorkspaceSid}
                  

                  Deletes a Workspace

                  Example

                  Example for deleting a workspace.

                  Loading Code Sample...
                      
                      
                      
                      

                      Workspace Instance Subresources

                      Every Workspace supports the following subresources.

                      Workers

                      /v1/Workspaces/{WorkspaceSid}/Workers
                      

                      Represents the resources that can process Tasks from this Workflow, such as agents in a call center or people working a help desk. See Workers for more information.

                      Activities

                      /v1/Workspaces/{WorkspaceSid}/Activities
                      

                      A worker's availability to handle a task is controlled by its Activity. Activities describe what a worker is currently doing and provide a meaningful label for real-time worker statistics. See Activities for more information.

                      TaskQueues

                      /v1/Workspaces/{WorkspaceSid}/TaskQueues
                      

                      TaskQueues hold tasks that are waiting to be assigned to Workers. Each TaskQueue specifies the capabilities workers must have to receive tasks from the queue. See TaskQueues for more information.

                      Workflows

                      /v1/Workspaces/{WorkspaceSid}/Workflows
                      

                      Workflows control how Tasks will be prioritized and routed to queues. Workflows can also escalate a Task's priority, move a Task to another queue after a timeout, or remove a Task from the Workspace entirely if it has not been assigned within some timeout. All Tasks enter the Workspace through a Workflow and will be managed by a Workflow until they are either assigned to a Worker or removed from the Workspace. See Workflows for more information.

                      Tasks

                      /v1/Workspaces/{WorkspaceSid}/Tasks
                      

                      Represents the Tasks waiting in this Workspace. See Tasks for more information.

                      Statistics

                      /v1/Workspaces/{WorkspaceSid}/Statistics
                      

                      Statistics are captured for each of TaskRouter's subresources. You can use these Statistics to build reporting dashboards and displays for your team. See Statistics for more information.

                      Events

                      /v1/Workspaces/{WorkspaceSid}/Events
                      

                      Events describe changes to your Workspace. Use these Events to build historical reports for your TaskRouter environment. See Events for more information.

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