> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Configure the NICE CXone handoff After you complete the [initial configuration](/docs/handoffs/nice-c-xone/initial-configuration) and share your credentials, your Ada team installs the CXone Utilities app on your AI Agent. When that is complete, the app appears in your AI Agent dashboard and you can configure the Handoff. > **Info** > > Your Ada team will install the CXone Utilities app and complete the backend integration setup. Contact your Ada representative to confirm when this step is finished before proceeding. If you are connecting more than one AI Agent to the same CXone instance, this is repeated for each AI Agent. ## Configure the Ada webhook CXone needs to receive conversation events from Ada, which are delivered to a webhook endpoint registered in your Ada dashboard. **To configure the webhook:** 1. In your Ada dashboard, navigate to **Platform → Webhooks**. 2. Create a new endpoint and set **Endpoint URL** to the value for your AI Agent's cluster: * **US:** `https://solutions.ada.support/messaging-connectors/cxone/webhooks/ada` * **EU:** `https://solutions.eu.ada.support/messaging-connectors/cxone/webhooks/ada` * **Canada:** `https://solutions.ca.ada.support/messaging-connectors/cxone/webhooks/ada` 3. Under **Subscribe to events**, select the following event check boxes: * `v1.conversation.created` * `v1.conversation.ended` * `v1.conversation.handoff.ended` * `v1.conversation.message` 4. Save the endpoint. ![The Ada New Endpoint form, with the CXone webhook URL entered and four conversation events selected under Subscribe to events.](/_fern-img/fe4c1df0243c18ebd83dc96d42fdb9ac110d08b558b18113901be985f8ed4dac.webp) ## Add the CXone Utilities block Each escalation creates a contact in CXone on the channel you specify, which is then routed to a skill by your Studio script. **To add the handoff block:** 1. In your handoff answer, add the **CXone Utilities** block. 2. Set **Select Action** to **Handoff to agent**. 3. Set the required inputs — **Ada conversation ID**, **Ada user ID**, **CXOne Channel Id**, and **User Email Address**. 4. Optionally set any of the additional fields documented below. Once the action is configured, your AI Agent can hand off to a human agent in CXone. ![The CXone Utilities block configured with the Handoff to agent action, showing the Ada conversation ID, Ada user ID, channel, email, attribute list, title, tags, and name inputs.](/_fern-img/ba7f5cd9a49b4d24f926c4df6129f8a54057b8a4bf942eaf50e86ea13701d107.webp) ## Handoff input fields The **Handoff to agent** action accepts the following inputs. | Field | Required | Description | | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | **Ada conversation ID** | Yes | Conversation ID. Populated from the `conversation_id` variable. | | **Ada user ID** | Yes | End user ID. Populated from the `end_user_id` variable. | | **CXOne Channel Id** | Yes | The CXone channel that receives the contact. | | **User Email Address** | Yes | Email address of the end user. CXone associates every conversation with a contact, and this value identifies that contact. | | **CXone contact attributes list** | No | Custom attributes to set on the CXone contact, as a comma-separated `key: value` list. | | **CXone end user attributes list** | No | Custom attributes to set on the end user's customer card, as a comma-separated `key: value` list. | | **Conversation title** | No | Title applied to the conversation in CXone. | | **Default agent display name** | No | Name shown to the end user for the agent before the agent's own name is available. | | **Tags** | No | Comma-separated tags applied to the contact in CXone. | | **User first name** | No | End user first name. | | **User last name** | No | End user last name. | | **Don't close CXone conversation** | No | When `true`, the CXone conversation is left open after the handoff ends. | | **Fetch Zendesk attachments** | No | When `true`, attachments hosted in Zendesk are retrieved and passed along with the conversation. | | **Default agent avatar url** | No | Avatar image shown to the end user for the agent. Available under **Select Optional Inputs**. | ## Pass custom attributes Custom attributes carry conversation context into CXone, where agents see them on the contact and on the customer card. They can also be used as routing criteria in your Studio script. Both attribute fields take a comma-separated list of `key: value` pairs, for example: ```text case_priority: high, case_order_id: order 12345 ``` Each key must match the **Ident** of a custom field configured in CXone. Use a **Case Custom Fields** ident in the **CXone contact attributes list** field, and a **Customer Card Custom Fields** ident in the **CXone end user attributes list** field. See [Configure custom fields](/docs/handoffs/nice-c-xone/initial-configuration#configure-custom-fields) for how to create these fields and find each **Ident**. ## Route across multiple channels A single AI Agent can escalate to more than one channel within the same CXone instance, which is useful when different conversation types should reach different teams. To route a conversation to a specific channel, set the **CXOne Channel Id** input on the handoff block to that channel's ID. Each channel must already exist in your CXone instance and have a Studio routing script assigned to it, as described in [Initial NICE CXone configuration](/docs/handoffs/nice-c-xone/initial-configuration). ## Related features * [Additional NICE CXone actions](/docs/handoffs/nice-c-xone/additional-actions) — check agent availability before escalating. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).