> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NICE CXone Chat

> Connect NICE CXone to create chats, send and receive messages, and end sessions from workflows.

This beta connector uses NICE's access-key token exchange and Patron Chat API v33.0. Serval stores the four credentials in its existing encrypted credential store and renews access tokens when needed. Workflows receive a connection reference, not credentials.

## Connect

1. Ask your NICE administrator for a **client ID**, **client secret**, **access key ID**, and **access key secret** for an account permitted to use the Patron Chat API.
2. Confirm the API hostname and token endpoint for that account. Supported token endpoints are `https://cxone.niceincontact.com/auth/token` and `https://cxone-gov.niceincontact.com/auth/token`. Enter the actual API hostname, such as `api-na1.niceincontact.com`, without a scheme or path.
3. Open **Integrations → Connect new → NICE CXone Chat** and enter the connection name, endpoints, and credentials.
4. Run **Validate NICE connection**. This checks token exchange and API connectivity without creating a chat. It does not prove that the account can reach your point of contact or deliver a message to an agent.

Changing the API host, token endpoint, client ID, or access key ID requires re-entering all four credentials. Unchanged or masked credential fields preserve their stored values.

## Use in workflows

Use the `niceCxone` SDK helpers with the native connection:

* `startChat({ pointOfContact, fromAddress, parameters? }, ctx)` returns `chatSessionId` and `contactId`. Confirm the point of contact with your NICE administrator.
* `sendMessage({ chatSessionId, label, message, chatTarget? }, ctx)` sends text to that chat.
* `receiveMessages({ chatSessionId, timeoutSeconds? }, ctx)` returns `messages` and the next `chatSessionId`. Poll timeout defaults to 30 seconds and accepts 0–60 seconds. HTTP 304 returns an empty array.
* `endChat({ chatSessionId }, ctx)` ends the session.

After every successful poll, save the returned `chatSessionId` and use it on subsequent calls. Reusing the original value can replay earlier messages. An empty HTTP 304 poll preserves the input session value. Use one poller per conversation. HTTP 404 can mean an ended or invalid session; handle it explicitly. Authentication, permission, and transport errors remain workflow errors.

Chat creation, sends, and termination are not automatically retried. A timeout can occur after NICE has acted. Check the chat before manually retrying to avoid duplicate chats or messages. A rejected token is evicted; a later request obtains a new token. The connection can retry an authenticated GET once after HTTP 401.

## Replace an existing proxy

Create a separate connection and a copy of the workflow. Replace the proxy calls with the helpers above; helpers return typed results or throw errors, rather than returning an `{ ok, httpStatus, data }` envelope.

Before switching traffic, test one complete conversation in a sandbox: create the chat, receive it in the agent console, exchange messages both ways, handle an empty poll, and end the session. Confirm token renewal and an invalid-session error. Keep the existing proxy workflow available for rollback until the pilot passes.

This connector does not change existing workflows or Azure Functions. When retiring a proxy, remove any debug logging of authorization headers or credential-bearing request parameters and rotate credentials if those logs exposed them.

See [NICE authentication](https://developer.niceincontact.com/Documentation/GettingStarted) and the [Patron Chat API](https://developer.niceincontact.com/API/PatronAPI).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.