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`	sid<AC> Not PII The SID of the Account that created the Workspace resource.
`date_created`	date_time<iso8601> Not PII The date and time in GMT when the resource was created specified in ISO 8601 format.
`date_updated`	date_time<iso8601> Not PII The date and time in GMT when the resource was last updated specified in ISO 8601 format.
`default_activity_name`	string Not PII The name of the default activity.
`default_activity_sid`	sid<WA> Not PII The SID of the Activity that will be used when new Workers are created in the Workspace.
`event_callback_url`	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. This parameter supports Twilio's Webhooks (HTTP callbacks) Connection Overrides.
`events_filter`	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`	string PII MTL: 30 DAYS The string that you assigned to describe the Workspace resource. For example `Customer Support` or `2014 Election Campaign`.
`multi_task_enabled`	boolean Not PII Whether multi-tasking is enabled. The default is `true`, which enables 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. In single-tasking each Worker would only receive a new reservation when the previous task is completed. Learn more at Multitasking.
`sid`	sid<WS> Not PII The unique string that we created to identify the Workspace resource.
`timeout_activity_name`	string Not PII The name of the timeout activity.
`timeout_activity_sid`	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`	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.
`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

Parameters in REST API 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. This parameter supports Twilio's Webhooks (HTTP callbacks) Connection Overrides.
`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. However, all workspaces should be created as multi-tasking. The default is `true`. 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. In single-tasking mode (legacy mode), each Worker will only receive a new reservation when the previous task is completed. Learn more at 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.

Example 1

Loading Code Sample...

Example JSON response

Create a Workspace

Fetch a Workspace resource

get

https://taskrouter.twilio.com/v1/Workspaces/{Sid}

Parameters

Parameters in REST API format
`sid` Path	get sid<WS> Not PII The SID of the Workspace resource to fetch.

Parameters in REST API format

sid

Path

get sid<WS> Not PII

The SID of the Workspace resource to fetch.

Example 1

Loading Code Sample...

Example JSON response

Fetch Workspace

List all Workspaces

get

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	get string PII MTL: 30 DAYS The `friendly_name` of the Workspace resources to read. For example `Customer Support` or `2014 Election Campaign`.

Parameters in REST API 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 1

Loading Code Sample...

Example JSON response

Read Workspace

Update a Workspace resource

post

https://taskrouter.twilio.com/v1/Workspaces/{Sid}

Parameters

Parameters in REST API format
`sid` Path	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. This parameter supports Twilio's Webhooks (HTTP callbacks) Connection Overrides.
`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. However, all workspaces should be maintained as multi-tasking. There is no default when omitting this parameter. A multi-tasking Workspace can't be updated to single-tasking unless it is not a Flex Project and another (legacy) single-tasking Workspace exists. Multi-tasking allows Workers to handle multiple Tasks simultaneously. In multi-tasking mode, each Worker can receive parallel reservations up to the per-channel maximums defined in the Workers section. In single-tasking mode (legacy mode), each Worker will only receive a new reservation when the previous task is completed. Learn more at 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`. For more information, see Queue Ordering.

Example 1

Loading Code Sample...

Example JSON response

Update a Workspace

Delete a Workspace resource

delete

https://taskrouter.twilio.com/v1/Workspaces/{Sid}

Parameters

Parameters in REST API format
`sid` Path	delete sid<WS> Not PII The SID of the Workspace resource to delete.

Parameters in REST API format

sid

Path

delete sid<WS> Not PII

The SID of the Workspace resource to delete.

Example 1

Loading Code Sample...

Example JSON response

Delete Workspace

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.

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.

Parameters

Example 1

Create a Workspace

Parameters

Example 1

Fetch Workspace

Parameters

Example 1

Read Workspace

Parameters

Example 1

Update a Workspace

Parameters

Example 1

Delete Workspace

Need some help?

Thank you for your feedback!

Thanks for your feedback!