How to Create and Manage Queues in NICE CXone Using the CXone APIs

How-To-Articles
1

How to Create and Manage Queues in NICE CXone Using the CXone APIs

What This Guide Covers

This guide details how to programmatically create, update, and delete queues within NICE CXone using the CXone APIs. Upon completion, you will have a functional script capable of automating queue management tasks, improving deployment velocity and reducing manual configuration errors. This allows for Infrastructure as Code (IaC) principles to be applied to the contact center.

Prerequisites, Roles & Licensing

  • CXone Licensing: CXone requires a license that includes the ACD (Automatic Call Distributor) functionality. The specific tier (e.g., CXone Essentials, CXone Premium) dictates access to certain API features and rate limits.
  • CXone Permissions: The API user account requires the following granular permissions:
    • ACD > Queue > View
    • ACD > Queue > Create
    • ACD > Queue > Update
    • ACD > Queue > Delete
  • OAuth Scopes: The OAuth token used for API authentication must include the acdx_queue scope.
  • External Dependencies: A REST client (e.g., curl, Postman, a programming language’s HTTP library like requests in Python) is required. Familiarity with JSON and REST APIs is assumed.
  • CXone Organization ID: The unique identifier for your CXone organization. This is essential for all API requests.

The Implementation Deep-Dive

1. Authentication & Obtaining an OAuth Token

Before interacting with the CXone APIs, you must authenticate and obtain an OAuth 2.0 access token. This token is included in the Authorization header of subsequent requests. CXone utilizes the Resource Owner Password Credentials grant type.

curl -X POST \
  'https://api.incontact.com/oauth2/v1/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=<YOUR_USERNAME>&password=<YOUR_PASSWORD>&scope=acdx_queue&client_id=<YOUR_CLIENT_ID>'

Replace <YOUR_USERNAME>, <YOUR_PASSWORD>, and <YOUR_CLIENT_ID> with your CXone credentials and Client ID. The Trap: Storing passwords directly in scripts is a severe security risk. Utilize environment variables or a secure credential management system. The returned JSON will contain the access_token. This token expires after a configured duration (typically 1 hour) and must be refreshed accordingly.

2. Creating a New Queue

The queue creation endpoint is POST /acdx/v1/queues. The request body must be a JSON payload defining the queue’s properties.

{
  "name": "My Programmatically Created Queue",
  "description": "This queue was created via the API.",
  "state": "ACTIVE",
  "skillIds": ["6d8b7a9c-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
  "wrapUpCodes": ["67890a1b-2c3d-4e5f-6a7b-8c9d0e1f"]
}

Explanation:

  • name: The display name of the queue.
  • description: A brief description of the queue’s purpose.
  • state: Can be ACTIVE or INACTIVE.
  • skillIds: An array of skill IDs associated with the queue. Agents must possess these skills to be eligible to receive interactions.
  • wrapUpCodes: An array of wrap-up code IDs associated with the queue.
curl -X POST \
  'https://api.incontact.com/acdx/v1/queues' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -d '{
  "name": "My Programmatically Created Queue",
  "description": "This queue was created via the API.",
  "state": "ACTIVE",
  "skillIds": ["6d8b7a9c-1a2b-3c4d-5e6f-7a8b9c0d1e2f"],
  "wrapUpCodes": ["67890a1b-2c3d-4e5f-6a7b-8c9d0e1f"]
}'

The Trap: Failing to provide valid skillIds and wrapUpCodes will result in a queue creation failure. These IDs must correspond to existing skills and wrap-up codes within your CXone organization. Always validate these IDs beforehand.

3. Updating an Existing Queue

The queue update endpoint is PUT /acdx/v1/queues/{queueId}. The queueId is the unique identifier of the queue you wish to modify. You only need to include the fields you want to update in the request body.

{
  "description": "Updated description for the queue."
}

curl -X PUT \
  'https://api.incontact.com/acdx/v1/queues/<QUEUE_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -d '{
  "description": "Updated description for the queue."
}'

The Trap: Providing an invalid queueId will result in a 404 Not Found error. Ensure you use the correct ID when updating a queue. Also, be mindful of field types; attempting to update a field with an incompatible type will result in an error.

4. Deleting a Queue

The queue deletion endpoint is DELETE /acdx/v1/queues/{queueId}.

curl -X DELETE \
  'https://api.incontact.com/acdx/v1/queues/<QUEUE_ID>' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

The Trap: Deleting a queue is irreversible. Before deleting, ensure it’s not actively in use by any agents or interactions. Deleting a queue while it has assigned agents or active interactions will lead to unpredictable behavior and potential service disruption. Consider setting the state to INACTIVE first before deleting.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Rate Limiting

  • The Failure Condition: API requests are throttled and return a 429 Too Many Requests error.
  • The Root Cause: The CXone API has rate limits in place to prevent abuse and ensure service stability.
  • The Solution: Implement retry logic with exponential backoff and jitter. Monitor the X-RateLimit-Remaining and X-RateLimit-Reset headers in the API response to proactively manage request frequency.

Edge Case 2: Invalid Skill/Wrap-Up Code IDs

  • The Failure Condition: Queue creation or update fails with a validation error.
  • The Root Cause: The provided skillIds or wrapUpCodes do not exist in the CXone organization.
  • The Solution: Before making API calls, verify the existence and validity of the skillIds and wrapUpCodes by querying the respective CXone APIs.

Edge Case 3: OAuth Token Expiration

  • The Failure Condition: API requests return a 401 Unauthorized error.
  • The Root Cause: The OAuth access token has expired.
  • The Solution: Implement a mechanism to automatically refresh the OAuth token before it expires, using the refresh token obtained during the initial authentication process.

Official References