Migrating from Ring Groups to Queues API

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 '{
ing_group_id": "60a7c1e2f1b3c4d5e6f7a8b9",
ser_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 '{
ing_group_id": "60a7c1e2f1b3c4d5e6f7a8b9",
ser_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