HandoffsNICE CXone

Initial NICE CXone configuration

Before your Ada team can enable the NICE CXone integration, complete the following prerequisite steps in your CXone instance. Once finished, share the collected information with your Ada representative.

This integration uses CXone’s Bring Your Own Channel (BYOC). Virtual Agent Hub (VAH) is not supported.

Collect your CXone identifiers

Two identifiers from your CXone instance are needed before anything else can be provisioned.

To collect your CXone identifiers:

  1. Business Unit ID — the identifier of your CXone business unit.
  2. Tenant ID — used to discover the API base URLs for your instance.

Register for Bring Your Own Channel access

Registering an application in the CXone developer portal produces the credentials the connector uses to authenticate against your instance.

To register for BYOC access:

  1. Register an application at CXone application registration, requesting access to the following APIs:
    • Admin API
    • Authentication API
    • Real-Time API
    • Digital Engagement API
  2. After registration completes, NICE sends the application key and secret by email. These form the Basic Authentication header the connector uses.
  3. Create an API user with Admin permissions and generate an access key ID and secret for the token endpoint.
  4. Create an employee account that your Ada team can use to sign in and test as an agent.

The exact set of APIs required can vary by instance. Your Ada team will confirm the final list with you during setup.

Create the BYOC channel integration

The channel integration tells CXone where to reach Ada. Creating it produces the Integration ID needed to create the chat channel itself.

To create the channel integration:

  1. Sign in to your CXone instance.

  2. Navigate to ACD → Digital → Bring Your Own Channel.

  3. Click Add.

  4. Enter a recognizable Name for the integration.

  5. Set the URL fields to Ada’s webhook endpoint for your AI Agent’s cluster:

    FieldValue
    Integration box URL<base-url>/messaging-connectors/cxone/webhooks/cxone
    Authorization URL<base-url>/messaging-connectors/cxone/webhooks/cxone/1.0/token
    Add action URL<base-url>/messaging-connectors/cxone/webhooks/cxone
    Reconnect action URL<base-url>/messaging-connectors/cxone/webhooks/cxone
    Remove action URL<base-url>/messaging-connectors/cxone/webhooks/cxone

    Replace <base-url> with the value for your cluster:

    • US: https://solutions.ada.support
    • EU: https://solutions.eu.ada.support
    • Canada: https://solutions.ca.ada.support

  6. Save the integration, then note its Integration ID and Name.

The CXone Bring Your Own Channel integration form, showing the Name field and the Integration box, Authorization, Add action, and Reconnect action URL fields populated with Ada webhook endpoints.

Create the chat channel

A channel must exist on the integration before conversations can be routed to it. Channels are created through the CXone Digital API rather than the admin UI.

To create the chat channel:

  1. Obtain a bearer token for your CXone API user.
  2. Send the following request, replacing <channel-name> with the name you want for the channel, <integration-id> with the Integration ID from the previous section, and <token> with your bearer token.
$curl --location 'https://api-na1.niceincontact.com/dfo/3.0/channels' \
>--header 'Authorization: Bearer <token>' \
>--header 'Content-Type: application/json' \
>--data '{
>    "id": "<channel-name>",
>    "name": "<channel-name>",
>    "idOnExternalPlatform": "<channel-name>",
>    "channelIntegrationId": "<integration-id>",
>    "realExternalPlatformId": "chat",
>    "isPrivate": true,
>    "hasTreeStructure": true,
>    "canReplyToAnyMessage": true,
>    "hasPublishing": true,
>    "hasAbilityToSendFiles": true,
>    "contentFormat": "html",
>    "externalPlatformAvatar": "chat",
>    "externalPlatformIcon": "livechat"
>}'

The API base URL in the request above is region-specific. If your instance is not hosted in North America, use the base URL returned by CXone discovery for your tenant. Your Ada team can run this request on your behalf if you prefer.

Enable channel access for roles

Agents can only work conversations on channels their role can access, so the new channel must be added to every role that handles escalations.

To enable channel access:

  1. Navigate to Digital → Roles.
  2. Select the role you want to update, such as an administrator or agent role.
  3. In the Channels list, grant the role the permissions it needs on the new channel.
The Channels permission grid in CXone role settings, listing channels alongside Reply, approval, deletion, and assignment permission columns.

Create the initialization workflow

Contacts arriving on the channel need a Studio workflow that assigns them to a CXone skill. Without it, escalated conversations are never routed to an agent.

To create the initialization workflow:

  1. In CXone, open Studio and create a new workflow.
  2. Add a Reqagent action to the workflow.
  3. In the action’s Properties, set Skill to the CXone skill that should receive escalated conversations. Create the skill first if it does not exist.
The Properties panel of a Reqagent action in CXone Studio, with a Skill dropdown selecting the skill that receives escalated conversations.

Create the conversation close trigger

When an agent resolves or closes a contact in CXone, Ada needs to be notified so the end user can resume chatting with the AI Agent. An automation trigger sends that notification.

To create the close trigger:

  1. Navigate to Digital → Automation Triggers and create a new trigger.

  2. Set Event to Case status changed.

    The CXone Add trigger form with the Event dropdown set to Case status changed.

  3. Under Conditions, select the Resolved and Closed check boxes for Contact status.

    The Conditions panel of a CXone trigger, with the Resolved and Closed contact status check boxes selected.

  4. Add a Job to the trigger and set its URL to Ada’s close-conversation endpoint for your cluster:

    • US: https://solutions.ada.support/messaging-connectors/cxone/webhooks/cxone/close-conversation
    • EU: https://solutions.eu.ada.support/messaging-connectors/cxone/webhooks/cxone/close-conversation
    • Canada: https://solutions.ca.ada.support/messaging-connectors/cxone/webhooks/cxone/close-conversation

Configure custom fields

Custom fields define which attributes a handoff can set on the CXone contact and on the end user’s customer card. Each field’s Ident is the key used when passing values from Ada.

To configure custom fields:

  1. Navigate to Digital → Custom Fields.

  2. Under Customer Card Custom Fields, create the fields you want to set on the end user.

  3. Under Case Custom Fields, create the fields you want to set on the contact.

    The CXone Custom Fields page, showing separate Customer Card Custom Fields and Case Custom Fields tables with field names and types.

  4. Open each field and note its Ident. The Ident is the key you pass from the Handoff in Ada, and it is distinct from the display Label.

    The CXone Edit custom field form, showing the Ident and Label fields along with visibility and editability toggles.

Configure skills and routing

Routing determines which CXone skill receives each escalated conversation. Custom attribute values can be used to route conversations from a single channel to different skills.

To configure routing:

  1. In Studio, create a routing script for the channel.
  2. Use the channel ID and any custom contact attributes as routing criteria to select the target skill.
A CXone Studio routing script showing a Begin node connected to a Reqagent node that assigns the contact to a skill.

Share with your Ada team

Once the steps above are complete, share the following with your Ada representative. Your Ada team will complete the remaining backend configuration.

  1. Business Unit ID
  2. Tenant ID
  3. Application key and secret from BYOC registration — share these securely, not in a shared channel
  4. API user access key ID and secret — share these securely, not in a shared channel
  5. Channel Integration ID and Name
  6. Channel ID of the chat channel you created
  7. Credentials for the employee account created for agent-side testing

Have any questions? Contact your Ada team, or email us at .