Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

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?

Workspace Resource

A Workspace is a container for your Tasks, Workers, TaskQueues, Workflows, and Activities. Each of these items exists within a single Workspace and is 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, priorities, and workers with a variety of capabilities. 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.

Workspace properties

Names in PHP format
accountSid
sid<AC> Not PII

The SID of the Account that created the Workspace resource.

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.

defaultActivityName
string Not PII

The name of the default activity.

defaultActivitySid
sid<WA> Not PII

The SID of the Activity that will be used when new Workers are created in the Workspace.

eventCallbackUrl
url Not PII

The URL we call when an event occurs. If provided, the Workspace will publish events to this URL, for example, to collect data for reporting. See Workspace Events for more information.

eventsFilter
string Not PII

The list of Workspace events for which to call event_callback_url. For example if EventsFilter=task.created,task.canceled,worker.activity.update, then TaskRouter will call event_callback_url only when a task is created, canceled, or a Worker activity is updated.

friendlyName

The string that you assigned to describe the Workspace resource. For example Customer Support or 2014 Election Campaign.

multiTaskEnabled
boolean Not PII

Whether multi-tasking is enabled. The default is false, which disables multi-tasking. Multi-tasking allows Workers to handle multiple Tasks simultaneously. When enabled (true), each Worker can receive parallel reservations up to the per-channel maximums defined in the Workers section. Otherwise, each Worker will only receive a new reservation when the previous task is completed. Learn more at [Multitasking][https://www.twilio.com/docs/taskrouter/multitasking].

sid
sid<WS> Not PII

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

timeoutActivityName
string Not PII

The name of the timeout activity.

timeoutActivitySid
sid<WA> Not PII

The SID of the Activity that will be assigned to a Worker when a Task reservation times out without a response.

prioritizeQueueOrder
enum:queue_order Not PII

The type of TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: LIFO or FIFO and the default is FIFO. For more information, see [Queue Ordering][https://www.twilio.com/docs/taskrouter/queue-ordering-last-first-out-lifo].

url
url Not PII

The absolute URL of the Workspace resource.

links
uri_map Not PII

The URLs of related resources.

Create a Workspace resource

post
https://taskrouter.twilio.com/v1/Workspaces
Parameters
Names in None format
friendly_name
Required
post string PII MTL: 30 DAYS

A descriptive string that you create to describe the Workspace resource. It can be up to 64 characters long. For example: Customer Support or 2014 Election Campaign.

event_callback_url
Optional
post url Not PII

The URL we should call when an event occurs. If provided, the Workspace will publish events to this URL, for example, to collect data for reporting. See Workspace Events for more information.

events_filter
Optional
post string Not PII

The list of Workspace events for which to call event_callback_url. For example if EventsFilter=task.created,task.canceled,worker.activity.update, then TaskRouter will call event_callback_url only when a task is created, canceled, or a Worker activity is updated.

multi_task_enabled
Optional
post boolean Not PII

Whether to enable multi-tasking. Can be: true to enable multi-tasking, or false to disable it. The default is false. Multi-tasking allows Workers to handle multiple Tasks simultaneously. When enabled (true), each Worker can receive parallel reservations up to the per-channel maximums defined in the Workers section. Otherwise, each Worker will only receive a new reservation when the previous task is completed. Learn more at [Multitasking][https://www.twilio.com/docs/taskrouter/multitasking].

template
Optional
post string Not PII

An available template name. Can be: NONE or FIFO and the default is NONE. Pre-configures the Workspace with the Workflow and Activities specified in the template. NONE will create a Workspace with only a set of default activities. FIFO will configure TaskRouter with a set of default activities and a single TaskQueue for first-in, first-out distribution, which can be useful when you are getting started with TaskRouter.

prioritize_queue_order
Optional
post enum:queue_order Not PII

The type of TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: LIFO or FIFO and the default is FIFO. For more information, see [Queue Ordering][https://www.twilio.com/docs/taskrouter/queue-ordering-last-first-out-lifo].

Example 1
        
        
        
        

        Fetch a Workspace resource

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

        The SID of the Workspace resource to fetch.

        Example
              
              
              
              

              List all Workspaces

              get
              https://taskrouter.twilio.com/v1/Workspaces

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

              Parameters
              Names in None format
              friendly_name
              Optional
              get string PII MTL: 30 DAYS

              The friendly_name of the Workspace resources to read. For example Customer Support or 2014 Election Campaign.

              Example
                    
                    
                    
                    

                    Update a Workspace resource

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

                    The SID of the Workspace resource to update.

                    default_activity_sid
                    Optional
                    post sid<WA> Not PII

                    The SID of the Activity that will be used when new Workers are created in the Workspace.

                    event_callback_url
                    Optional
                    post url Not PII

                    The URL we should call when an event occurs. See Workspace Events for more information.

                    events_filter
                    Optional
                    post string Not PII

                    The list of Workspace events for which to call event_callback_url. For example if EventsFilter=task.created,task.canceled,worker.activity.update, then TaskRouter will call event_callback_url only when a task is created, canceled, or a Worker activity is updated.

                    friendly_name
                    Optional
                    post string PII MTL: 30 DAYS

                    A descriptive string that you create to describe the Workspace resource. For example: Sales Call Center or Customer Support Team.

                    multi_task_enabled
                    Optional
                    post boolean Not PII

                    Whether to enable multi-tasking. Can be: true to enable multi-tasking, or false to disable it. The default is false. Multi-tasking allows Workers to handle multiple Tasks simultaneously. When enabled (true), each Worker can receive parallel reservations up to the per-channel maximums defined in the Workers section. Otherwise, each Worker will only receive a new reservation when the previous task is completed. Learn more at [Multitasking][https://www.twilio.com/docs/taskrouter/multitasking].

                    timeout_activity_sid
                    Optional
                    post sid<WA> Not PII

                    The SID of the Activity that will be assigned to a Worker when a Task reservation times out without a response.

                    prioritize_queue_order
                    Optional
                    post enum:queue_order Not PII

                    The type of TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: LIFO or FIFO and the default is FIFO. For more information, see [Queue Ordering][https://www.twilio.com/docs/taskrouter/queue-ordering-last-first-out-lifo].

                    Example 1
                          
                          
                          
                          

                          Delete a Workspace resource

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

                          The SID of the Workspace resource to delete.

                          Example
                                
                                
                                
                                

                                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 the Worker Resource 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 the Activity Resource 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][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 the Workflow Resource for more information.

                                Tasks

                                /v1/Workspaces/{WorkspaceSid}/Tasks

                                Represents the Tasks waiting in this Workspace. See the Task Resource 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 Workspace 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 the Event Resource for more information.

                                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.