Migrating from Ring Groups to Queues API

Note: On July 31, 2026, Talkdesk will deprecate Ring Groups API. To maintain service continuity, customers using Ring Group API in custom implementations are required to migrate to Queues API before this date.

What is Changing

The following public APIs are covered in this guide:

Authentication

All Queues API endpoints use OAuth 2.0 with the Authorization Code flow.

Required scopes per endpoint:

queues:read — GET /ccaas/queues
queues:write — POST /ccaas/queues/users, DELETE /ccaas/queues/users
queues-users:read — GET /ccaas/queues/{queue_id}/users

Example — obtain a token:

curl -X POST https://api.talkdeskapp.com/oauth/token
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=authorization_code
&code={auth_code}
&client_id={client_id}
&client_secret={client_secret}"

Include the token in all subsequent requests:

Authorization: Bearer {access_token}

1. List Queues

Returns a paginated list of queues for the account. The new endpoint adds filtering by name, queue ID, and prompt IDs, plus sorting support.

FROM — Ring Groups: GET /ring-groups

curl -X GET https://api.talkdeskapp.com/ring-groups
-H "Authorization: Bearer {access_token}"

TO — Queues: GET /ccaas/queues

curl -X GET "https://api.talkdeskapp.com/ccaas/queues?page=1&per_page=20"
-H "Authorization: Bearer {access_token}"

Search by name:

curl -X GET "https://api.talkdeskapp.com/ccaas/queues?name=support"
-H "Authorization: Bearer {access_token}"

Sort results:

curl -X GET "https://api.talkdeskapp.com/ccaas/queues?order_by=name:asc"
-H "Authorization: Bearer {access_token}"

Example response:

{"total": 3,
"count": 3,
"page": 1,
"per_page": 20,
"_embedded": {
"queues": [
{
"id": "60a7c1e2f1b3c4d5e6f7a8b9",
"name": "support",
"description": "General support queue",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-03-20T14:30:00Z"
}
]
}}

What changed:

• Scope: queues:read (new)
• Filter by name, id, or prompt_ids using query parameters
• Sort with order_by=name:asc or name:desc
• Pagination: page and per_page (1–100, default 20)

2. Assign Users to Queues

Assign one or more users to one or more queues in a single bulk request.

Key behaviors:

• Idempotent: assigning a user who already has the queue is a no-op and returns success
• Non-transactional: a partial failure may apply some assignments but not others
• Always check the result field in the response — a 200 OK does not mean everything succeeded

FROM — Ring Groups

POST /actions/users/assign-ring-groups (bulk)
PUT /users/:id/ring-groups (single user)

curl -X POST https://api.talkdeskapp.com/actions/users/assign-ring-groups
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d '{"ring_group_id": "60a7c1e2f1b3c4d5e6f7a8b9",
"user_ids": ["user_001", "user_002"]}'

TO — Queues: POST /ccaas/queues/users

The body is an array — assign users to multiple queues in one request:

curl -X POST https://api.talkdeskapp.com/ccaas/queues/users
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d '[
{"id": "60a7c1e2f1b3c4d5e6f7a8b9",
"users": ["user_001", "user_002", "user_003"]},
{"id": "70b8d2f3g2c4d5e6f7a8c0",
"users": ["user_001"]}
]'

Successful response:

HTTP 200
{"result": "OK",
"errors": []}

Partial failure (still HTTP 200 — check result!):

HTTP 200
{"result": "KO",
"errors": [
{
"queue_id": "70b8d2f3g2c4d5e6f7a8c0",
"user_id": "user_001",
"error": "USER_NOT_FOUND",
"description": "The specified user does not exist"
}
]}

What changed:

• Scope: queues:write (new)
• Body is always an array, even for a single assignment
• Supports bulk assignment to multiple queues in one call
• Response is a result/errors object — always inspect result even on 200 OK
• Max 100 users per queue object per request

3. Unassign Users from Queues

Remove one or more users from one or more queues in a single bulk request.

Key behaviors:

• Idempotent: removing a user not in the queue is a no-op and returns success
• Non-transactional: a partial failure may apply some removals but not others
• Every user must retain at least one queue — attempting to remove a user's last queue returns 409
• Always check the result field in the response — a 200 OK does not mean everything succeeded

FROM — Ring Groups: POST /actions/users/unassign-ring-groups

curl -X POST https://api.talkdeskapp.com/actions/users/unassign-ring-groups
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d '{"ring_group_id": "60a7c1e2f1b3c4d5e6f7a8b9",
"user_ids": ["user_001", "user_002"]}'

TO — Queues: DELETE /ccaas/queues/users

Note: this uses the DELETE method with a JSON request body:

curl -X DELETE https://api.talkdeskapp.com/ccaas/queues/users
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d '[
{"id": "60a7c1e2f1b3c4d5e6f7a8b9",
"users": ["user_001", "user_002"]}
]'

Successful response:

HTTP 200
{"result": "OK",
"errors": []}

User has only one queue (cannot unassign):

HTTP 409
{"code": "0490014",
"message": "User has only one queue assigned"}

What changed:

• Scope: queues:write (new)
• Method changed from POST to DELETE (with a JSON body)
• Body is always an array
• Cannot remove a user's last queue — assign them to another first
• Max 100 users per queue object, up to 100 queue objects per request

4. List Users in a Queue

Get a paginated list of users assigned to a specific queue. Supports filtering by active status.

FROM — Ring Groups: GET /ring-groups/:id/users

curl -X GET https://api.talkdeskapp.com/ring-groups/60a7c1e2f1b3c4d5e6f7a8b9/users
-H "Authorization: Bearer {access_token}"

TO — Queues: GET /ccaas/queues/{queue_id}/users

curl -X GET "https://api.talkdeskapp.com/ccaas/queues/60a7c1e2f1b3c4d5e6f7a8b9/users?page=1&per_page=50"
-H "Authorization: Bearer {access_token}"

Filter to active users only:

curl -X GET "https://api.talkdeskapp.com/ccaas/queues/60a7c1e2f1b3c4d5e6f7a8b9/users?active=true"
-H "Authorization: Bearer {access_token}"

Example response:

{"total": 3,
"count": 2,
"page": 1,
"per_page": 2,
"queue_id": "60a7c1e2f1b3c4d5e6f7a8b9",
"_embedded": {
"users": [
{
"id": "user_001",
"_links": {
"self": { "href": "https://api.talkdeskapp.com/users/user_001" }
}
},
{
"id": "user_002",
"_links": {
"self": { "href": "https://api.talkdeskapp.com/users/user_002" }
}
}
]
},
"_links": {
"self": { "href": "<https://api.talkdeskapp.com/ccaas/queues/60a7c1e2f1b3c4d5e6f7a8b9/users?page=1&per_page=2"> },
"page": { "href": "<https://api.talkdeskapp.com/ccaas/queues/60a7c1e2f1b3c4d5e6f7a8b9/users?page=1&per_page=2"> },
"prev": null,
"next": { "href": "<https://api.talkdeskapp.com/ccaas/queues/60a7c1e2f1b3c4d5e6f7a8b9/users?page=2&per_page=2"> }
}}

What changed:

• Scope: queues-users:read (new — separate from queues:read)
• Supports active=true/false query parameter to filter by user status
• Response follows HAL format with embedded users and links for pagination
• Default page size is 50 (max 100)

Scope Changes Summary

Legacy scope
New Scope
Endpoint
ring-groups:read
queues:read
GET /ccaas/queues
ring-groups:write
queues:write
POST /ccaas/queues/users
ring-groups:write
queues:write
DELETE /ccaas/queues/users
ring-groups:read
queues-users:read
GET /ccaas/queues/{queue_id}/users