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 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.
Please note that a Flex project can only have a single Workspace.
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.
While we still support the creation of a single-tasking Workspace (legacy mode) we advise you to only create multi-tasking Workspaces.
We also encourage you to start the migration of all your existing single-tasking Workspaces to multi-tasking. Please be advised that once a Workspace has been migrated to multi-tasking it can longer be converted back to single-tasking.
Workspace 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 Workspace resource. |
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. |
default_activity_name
|
The name of the default activity. |
default_activity_sid
|
The SID of the Activity that will be used when new Workers are created in the Workspace. |
event_callback_url
|
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. This parameter supports Twilio's Webhooks (HTTP callbacks) Connection Overrides. |
events_filter
|
The list of Workspace events for which to call |
friendly_name
|
The string that you assigned to describe the Workspace resource. For example |
multi_task_enabled
|
Whether multi-tasking is enabled. The default is |
sid
|
The unique string that we created to identify the Workspace resource. |
timeout_activity_name
|
The name of the timeout activity. |
timeout_activity_sid
|
The SID of the Activity that will be assigned to a Worker when a Task reservation times out without a response. |
prioritize_queue_order
|
The type of TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: |
url
|
The absolute URL of the Workspace resource. |
links
|
The URLs of related resources. |
Create a Workspace resource
https://taskrouter.twilio.com/v1/Workspaces
Parameters
Parameters in REST API format | |
---|---|
friendly_name
Required
|
A descriptive string that you create to describe the Workspace resource. It can be up to 64 characters long. For example: |
event_callback_url
Optional
|
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. This parameter supports Twilio's Webhooks (HTTP callbacks) Connection Overrides. |
events_filter
Optional
|
The list of Workspace events for which to call event_callback_url. For example, if |
multi_task_enabled
Optional
|
Whether to enable multi-tasking. Can be: |
template
Optional
|
An available template name. Can be: |
prioritize_queue_order
Optional
|
The type of TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: |
Example 1
Fetch a Workspace resource
https://taskrouter.twilio.com/v1/Workspaces/{Sid}
Parameters
Parameters in REST API format | |
---|---|
sid
Path
|
The SID of the Workspace resource to fetch. |
Example 1
List all Workspaces
https://taskrouter.twilio.com/v1/Workspaces
By default, this will return the first 50 Workspaces. Supply a PageSize parameter to fetch more than 50 Workspaces. See pagination information for more information.
Parameters
Parameters in REST API format | |
---|---|
friendly_name
Optional
|
The |
Example 1
Update a Workspace resource
https://taskrouter.twilio.com/v1/Workspaces/{Sid}
Parameters
Parameters in REST API format | |
---|---|
sid
Path
|
The SID of the Workspace resource to update. |
default_activity_sid
Optional
|
The SID of the Activity that will be used when new Workers are created in the Workspace. |
event_callback_url
Optional
|
The URL we should call when an event occurs. See Workspace Events for more information. This parameter supports Twilio's Webhooks (HTTP callbacks) Connection Overrides. |
events_filter
Optional
|
The list of Workspace events for which to call event_callback_url. For example if |
friendly_name
Optional
|
A descriptive string that you create to describe the Workspace resource. For example: |
multi_task_enabled
Optional
|
Whether to enable multi-tasking. Can be: |
timeout_activity_sid
Optional
|
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
|
The type of TaskQueue to prioritize when Workers are receiving Tasks from both types of TaskQueues. Can be: |
Example 1
Delete a Workspace resource
https://taskrouter.twilio.com/v1/Workspaces/{Sid}
Parameters
Parameters in REST API format | |
---|---|
sid
Path
|
The SID of the Workspace resource to delete. |
Example 1
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.
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.