Digital Chat Web SDK

SDK: GitHub

API Reference: GitHub Pages

Sample App: GitHub

NPM Package: npmjs.com

The chat web SDK lets you create your own digital chat application, or add digital chat into an existing web application. It lets you use NiCE CXone digital infrastructure in a UI of your choosing. This is a JavaScript-based SDK that supports both LiveChat and Chat Messaging—both synchronous and asynchronous messaging. You can also set up either singleClosed In a single-threaded app, each contact has one chat thread that handles any interaction they have with your organization. or multi-threadedClosed In a multi-threaded app, contacts can create as many threads as they want to discuss new topics. These threads can be active at the same time. messaging. This SDK gives you more control over NiCE CXone on your website. It helps you avoid certain technical limitations that some websites have. For example, your site may not allow external code, which could prevent the native NiCE CXone digital chat from running.

The SDK supports the following features:

  • Digital chat messaging
  • OAuth2.0 for authorization
  • Contact identification and custom fields
  • List of threads and thread recovery
  • Attachments
  • Rich messages
  • Indicators for typing, message seen, and message delivered
  • System messages like case status events or assignment events
  • Queue position events

  • Proactive actions (pop-ups, welcome messages)

This SDK is written in TypeScript 4.9+. You must also use a custom application bundler like webpack or Create React App.

SDK Resources

The top of this page or the drop-down below provide links to the various SDK resources.

Your developers can get the SDK from GitHub. The repository has a README that helps the developer get started. It also contains documentation for events and the API reference. The more user-friendly API reference is hosted separately through github.io.

You can also look at the sample application. This lets you try out the chat and look at the correlating source code.

Developers import the SDK as an NPM package. The package entry on npmjs.com contains all the same content and instructions for setting up and building with the SDK.

SDK: GitHub

API Reference: GitHub Pages

Sample App: GitHub

NPM Package: npmjs.com

Key Terms

Term Details
Thread A conversation within the chat application. The first message sent by either the agent or contactClosed The person interacting with an agent, IVR, or bot in your contact center. begins a thread. Each consecutive message in the conversation is added to the thread. Threads are objects that contain each message. Messages are structured by the author of the message. A threadId identifies an entire conversation, and all messages within a conversation have a message ID. A thread ends when the conversation ends.
Single-Thread An application design where the contact can only have one conversation at a time.
Messaging channel (multi-thread) An asynchronous channel where a customer can hold several long-lived conversations at once. The SDK exposes getThreadList(), thread naming, and archiving here.
Channel In the context of Digital Experience (DX), channel refers to the type of messaging or the platform used for communication. For example, you could have a WhatsApp real-time messaging channel. The mobile SDK lets you add a chat messaging channel to your mobile application. A channel is created in the NiCE CXone platform. This determines the settings of the channel along with a channel ID. You use this ID to initiate the chat channel when an application user opens the chat.
ChannelId The ID of the digital chat channel created in the Digital section of NiCE CXone. You can find this in the chat channel's settings in NiCE CXone (ACD > Digital > Points of Contact Digital > Chat > Initialization & Test).
BrandId This is like a tenantClosed High-level organizational grouping used to manage technical support, billing, and global settings for your NiCE CXone system. ID for Digital Experience (DX). It's used to initialize the chat. You can find this in the chat channel's settings in NiCE CXone (ACD > Digital > Points of Contact Digital > Chat > Initialization & Test).
CustomerId The unique ID of the chat end user. The SDK creates this ID when the chat is initialized. If you have OAuth set up, this ID stays the same for each contact across all their devices. If you do not have OAuth set up, this ID is different for each device; the ID becomes like a guest login.
Region or Environment The location in the world where your NiCE CXone deployment is hosted. This can be: Australia (AU1), Canada (CA1), Europe (EU1), Japan (JP1), North America (NA1), or United Kingdom (UK1). The developer must use the same region where your NiCE CXone system is hosted, otherwise the chat connection is rejected.
Contact, Customer, and User These terms all refer to the end-user of the mobile application. The online help typically uses the term contact. In the SDK documentation and code comments, you are likely to see customer and user.
NiCE CXone The core platform where you manage and access all the customer experience tools that NiCE CXone offers. Depending on which chat features you want to offer in your mobile application, an administrator with the necessary user account permissions must complete several setup tasks in NiCE CXone.
Digital Experience (DX) The section of NiCE CXone where you can manage everything about digital channels.
Brand Your company/account in CXone, identified by a numeric brandId. All chat configuration lives under a brand.
Livechat channel (single-session) A synchronous, agent-routed session. Chat must be explicitly started (startChat()) and can be ended (endChat()), and the customer may wait in a queue. The SDK returns a LivechatThread for these channels.
Thread One conversation within a channel, identified by a thread ID. It carries the message history and is your main handle for sending and receiving messages.
Contact (a.k.a. case) A single routed interaction created from a thread — the unit an agent actually picks up and works. One thread can produce multiple contacts over its lifetime (e.g. a new contact each time the customer re-engages after closure).
Message A single item in a thread — text, an attachment, or rich content — authored by the customer or an agent.
Agent A human (or bot) on the CXone side who handles the contact. Agent assignment and typing surface as events.
Visitor / visit Lightweight analytics identifiers for the browsing person (visitorId) and their current browsing session (visitId). They are generated for you if you don't supply them and mainly matter for proactive chat and analytics.

Prerequisites

  • TypeScript 4.9+ (the SDK ships its own type definitions).

  • ES2022 runtime. The SDK relies on standard browser APIs: WebSocket, EventSource, crypto, Intl, Promise, EventTarget, CustomEvent, JSON, Date.

  • A module bundler (webpack, Vite, Create React App, etc.). The SDK is distributed as ES modules and is meant to be bundled into your app.

  • A custom application (you build the UI).

Before You Start Developing

Consider the following items before building with the mobile SDK:

  • Do you have both an administrator and agent account in NiCE CXone? Can an administrator assist you in setting up the necessary features in the NiCE CXoneplatform?
  • Do you have existing chat channels, or do you want to create a new one?
  • Do you want to offer single- or multi-threaded conversations?
  • Which types of rich messages do you want to set up? What are some use cases where you can leverage these interactive messages?
  • Will you use proactive actions like pop-ups or welcome messages?

Initialize Chat Properly

Your developers must connect your application to NiCE CXone to begin communication back and forth. This creates a WebSocket connection. Developers can do so by calling await sdk.connect(). Be sure to instruct your developers to do so only for active chat conversations. This ensures that the WebSocket only runs when necessary.

Installation

npm install @nice-devone/nice-cxone-chat-web-sdk

Initialization

Import the default export and create an instance with your brand, channel, and region. storageand cacheStorage are required options — pass null to disable persistence and caching, or pass real implementations to enable them (see below).

Minimal Setup (No Persistence)

import ChatSdk, { EnvironmentName } from '@nice-devone/nice-cxone-chat-web-sdk';

const sdk = new ChatSdk({

brandId: 1234,

channelId: 'chat_abcd1234-...',

customerId: 'your-customer-id',

environment: EnvironmentName.EU1,

storage: null,

cacheStorage: null,

});

Production Setup (With Persistence)

import ChatSdk, { CacheStorage, EnvironmentName } from '@nice-devone/nice-cxone-chat-web-sdk';

const sdk = new ChatSdk({

brandId: 1234,

channelId: 'chat_abcd1234-...',

customerId: 'your-customer-id',

environment: EnvironmentName.EU1,

storage: window.localStorage,

cacheStorage: new CacheStorage(window.localStorage),

});

Notes on Required Options

  • brandId and channelId — identify the channel (create a chat channel in CXone to obtain them).

  • customerId — required unless you use secured sessions (securedSession), in which case the platform establishes identity. See authentication.md.

  • environment — selects the CXone region (e.g. EU1, NA1, AU1). Picking the wrong region means the SDK talks to the wrong gateway.

Connecting

The SDK does not connect automatically. Open the WebSocket explicitly:

await sdk.connect();

connect() resolves to true when it creates the connection and false if one already exists — it never opens a second socket. Call it once per page lifetime; the SDK owns reconnection, heartbeat, and token refresh from there.

Important: Only call connect() for active chat conversations so the WebSocket runs only when necessary.

Inspecting Channel Info

You can query channel configuration and availability without opening a connection — useful for deciding whether to show the chat widget.

const info = await sdk.getChannelInfo();

const { status } = await sdk.getChannelAvailability(); // 'online' | 'offline'

getChannelInfo() returns a ChannelInfo object with:

  • isLiveChat— whether this is a livechat channel.

  • settings — file upload restrictions (settings.fileRestrictions) and feature flags (settings.features).

  • translations — localized strings for the configured language.

Both calls are also available as standalone functions if you need channel data before constructing an SDK instance.

Opening a Thread and Sending / Receiving Messages

A Thread is your handle to one conversation. Get it with getThread(threadId) — synchronous, no network request. Returns Thread for messaging channels or LivechatThread for livechat. Call only after connect()resolves.

import { ChatEvent, isMessageCreatedEvent } from '@nice-devone/nice-cxone-chat-web-sdk';

import type { ChatEventData } from '@nice-devone/nice-cxone-chat-web-sdk';

const thread = sdk.getThread('my-thread-id');

// Listen for incoming messages BEFORE sending.

thread.onThreadEvent(

ChatEvent.MESSAGE_CREATED,

(event: CustomEvent<ChatEventData>) => {

if (!isMessageCreatedEvent(event.detail)) return;

const { message } = event.detail.data;

console.log('New message:', message);

},

);

// Load existing history (optional).

const recovered = await thread.recover();

console.log('Recovered messages:', recovered.messages);

// Send a text message.

await thread.sendTextMessage('Hello! I need some help.');

Notes

  • onThreadEvent(type, handler) returns an unregister function. Narrow event.detail with type guards before reading data.

  • recover() loads thread state from the server. Wrap in try/catch — it rejects with ThreadRecoverFailedError if the thread doesn't exist.

  • Livechat channels: call await (thread as LivechatThread).startChat() before sending messages.

Full Example

import ChatSdk, {

ChatEvent,

EnvironmentName,

generateId,

isMessageCreatedEvent,

} from '@nice-devone/nice-cxone-chat-web-sdk';

import type { ChatEventData } from '@nice-devone/nice-cxone-chat-web-sdk';

async function startChat() {

// 1. Initialize.

const sdk = new ChatSdk({

brandId: 1234,

channelId: 'chat_abcd1234-...',

customerId: generateId(),

environment: EnvironmentName.EU1,

storage: null,

cacheStorage: null,

onError: (error) => console.error('Chat SDK error:', error),

});

// 2. Check availability before showing UI.

const { status } = await sdk.getChannelAvailability();

if (status === 'offline') {

console.log('No agents available right now.');

}

// 3. Connect once.

await sdk.connect();

// 4. Open a thread and listen for messages.

const thread = sdk.getThread(generateId());

thread.onThreadEvent(

ChatEvent.MESSAGE_CREATED,

(event: CustomEvent<ChatEventData>) => {

if (isMessageCreatedEvent(event.detail)) {

console.log('Message:', event.detail.data.message);

}

},

);

// 5. Send the first message.

await thread.sendTextMessage('Hi there!');

}

startChat();

What's Next

  • configuration.md — environments, custom endpoints, channel info, and all SDK options.

  • authentication.md — secured sessions and customer identity.

  • connection-guidance.md — connection lifecycle, reconnect, and auth events.

  • events-and-errors.md — the event model, type guards, and SDK error types.

  • messaging-and-rich-content.md — attachments, postbacks, quick replies, and rich messages.

  • threads-and-livechat.md — multi-thread vs. livechat, queues, typing, and read receipts.

  • proactive-and-visitors.md — proactive chat, visitors, and visits.

  • migration.md — upgrading between SDK versions.