Queues API

Overview

The Queues API provides programmatic control over the routing of customer interactions to agents. Within Talkdesk, a queue represents a logical grouping that holds interactions, such as calls or chats, until they are handled by an available agent.

Key Features

List queues: Browse all account-level queues with support for name-based searching and result sorting.

Assign agents to queues: Designate agents as eligible to receive and handle interactions from specific queues.

Remove agents from queues: Update and manage agent assignments to reflect changing team responsibilities.

Inspect queue membership: Retrieve a list of agents currently assigned to a specific queue

Queues Benefits

As the successor to the Ring Groups API, this interface delivers improved consistency, bulk operation support, and advanced filtering functionality.

Bulk operations: Perform agent assignments or removals across multiple queues within a single request, eliminating the need for iterative calls per group.

Unified endpoints: Two dedicated endpoints (POST and DELETE /ccaas/queues/users) replace three legacy ring groups endpoints (POST /actions/users/assign-ring-groups, POST /actions/users/unassign-ring-groups, and PUT /users/:id/ring-groups).

Advanced queue filtering: Browse and manage queues with support for name-based searching, ID or prompt ID filtering, and result sorting(capabilities not available via the Ring Groups API).

Active status filtering: Refine queue membership lists by specifically filtering for agents who are currently active.

Detailed error reporting: Assign and unassign responses provide granular insights through an errors array, pinpointing specific user-queue failures instead of generic error codes.

Idempotency: Safely retry operations without unintended side effects. The API gracefully handles redundant assignments or removals that have already been processed.

HAL-compliant pagination: List responses use standard HAL formatting, providing self, prev, and next links for consistent and efficient results navigation.

Granular OAuth scopes: Distinct queues:read, queues:write, and queues-users:read scopes enable precise access management tailored to specific integration needs.

General Availability: Core operations are fully GA, providing a stable, production-ready interface backed by official support and a clear lifecycle path.

📘

Use Case

As a real-life example, consider the scenario where Talkdesk administrators who deal with queue management daily are able, using the Queues API, to (a) extract machine-readable records of all the accounts’ queues, (b) of all agents assigned to a specific queue, (c) add and remove users from queues programmatically, facilitating management.

Usage

The Queues API allows a caller to:

• List all of the queues in an account, with optional filters.
• Query the list of users assigned to a queue.
• Programmatically add and remove users from a queue.

👍

Availability Date

Queues API will be in General Availability on April 30, 2026.

📘

Supported Regions and Base URLs

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.