NICE CXone Chat Web SDK

• Official SDK Documentation
• NPM package
• Sample Web App

Guides

In-depth developer guides live in docs_guides/:

• Getting started — install, initialize, connect, and send your first message.
• Configuration reference — every ChatSDKOptions field, environments, storage, and channel info.
• Authentication — Secured Sessions, customer identity, and token lifecycle.
• Connection, reconnect & heartbeat — the connection lifecycle, reconnect/recovery (recover after connect vs. reconnect), FetchThreadList vs Recover, and what the SDK handles for you.
• Events & errors — the event catalog, type guards, and error handling.
• Messaging & rich content — sending/receiving, rich content, streamed (GenAI) messages, and attachments.
• Threads & livechat — messaging vs livechat, contacts/cases, custom fields, and group chat.
• Proactive & visitors — proactive actions, page views, and visitor tracking.
• Migration — upgrading between SDK versions and replacing deprecated APIs.

Requirements

• TypeScript 4.9+
• Runtime: ES2022 (WebSocket, Intl, Promise, EventTarget, CustomEvent, JSON, Date, crypto, EventSource, etc.)
• Custom application bundler (webpack, create-react-app, etc.)

Quickstart

1. Import the SDK into your project

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

2. Login to your Brand and create a Chat Channel, setup their respective IDs in the SDK init (brandId, channelId)
3. Connect your project to the CXone environment (environment)
4. Fork the code sandbox and test your configuration
5. Implement your own UI layer, take inspiration from the Sample Web App...

SDK Usage examples

Import the SDK

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

Init

// Minimal setup — no persistence or caching
const sdk = new ChatSdk({
  brandId: 123,
  channelId: 'my-channel-id',
  customerId: 'customer-id',
  environment: EnvironmentName.EU1,
  cacheStorage: null,
  storage: null,
});
Copy

cacheStorage and storage are required. Pass null if you do not want the SDK to cache or persist anything. For production use, pass real instances so customer identity, scroll tokens and other state survive page reloads:

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

const sdk = new ChatSdk({
  brandId: 123,
  channelId: 'my-channel-id',
  customerId: 'customer-id',
  environment: EnvironmentName.EU1,
  cacheStorage: new CacheStorage(window.localStorage),
  storage: window.localStorage,
});
Copy

Connect to server

By default, the SDK will not automatically connect to the server. You need to call the connect() method to establish a connection.

await sdk.connect()
Copy

Channel Info

It will return information about the initialized channel, including feature toggle status, translations, file upload restrictions, theme color settings, and more.

await sdk.getChannelInfo()
Copy

Channel Availability Info

It will return the online/offline status information for the current channel.

await sdk.getChannelAvailability()
Copy

Thread

Get or create a Thread instance:

const thread = sdk.getThread('thread-id');
// Optionally recover a thread state (messages) from the server
const threadRecoveredData = await thread.recover();
console.log(threadRecoveredData.messages);
Copy

getThread() is synchronous — it returns a Thread (or LivechatThread for livechat channels) without any network call.

Send a message

await thread.sendTextMessage('Message text');
Copy

Listen for new messages

thread.onThreadEvent(ChatEvent.MESSAGE_CREATED, (event: CustomEvent<ChatEventData>) => {
    if (!isMessageCreatedEvent(event.detail)) {
        return;
    }
    const message = event.detail.data.message;
    console.log(message);
});
Copy

Load more messages

loadMoreMessages() returns null when there are no more messages to load (no scroll token), so the result must be null-checked:

const loadMoreMessageResponse = await thread.loadMoreMessages();
if (loadMoreMessageResponse !== null) {
    console.log(loadMoreMessageResponse.data.messages);
}
Copy

Mark messages as read

await thread.lastMessageSeen();
Copy

Livechat

startChat() and endChat() are available only on livechat channels — they are methods of LivechatThread, which is the concrete type returned by sdk.getThread(...) when the channel is configured as livechat. Livechat channel needs to call startChat() method first to start the chat. Customers might end the chat by calling endChat() method.

const thread = sdk.getThread('thread-id') as LivechatThread;
await thread.startChat();
Copy

Get position in queue:

sdk.onChatEvent(ChatEvent.SET_POSITION_IN_QUEUE, (event) => {
    if (isSetPositionInQueueEvent(event)) {
        setQueuePosition(event.detail.data.positionInQueue);
    }
});
Copy

Multi-thread

Get list of threads

const threads = await sdk.getThreadList();
Copy

Load metadata

const metadata = await thread.getMetadata();
Copy

Archive thread

await thread.archive();
Copy

Set thread name

await thread.setName('New thread name');
Copy

Attachments

await thread.sendAttachments(fileList);
Copy

Typing

Send typing events. Can be called multiple times, for example on every keypress:

thread.keystroke();
// Optionally call stopTyping() when the user stops typing or leaves
thread.stopTyping();
Copy

Receive typing events:

// Listen for START and STOP typing events
thread.onThreadEvent(ChatEvent.AGENT_TYPING_STARTED, (event: CustomEvent<ChatEventData>) => {
   // Do something with the event
});

thread.onThreadEvent(ChatEvent.AGENT_TYPING_ENDED, (event: CustomEvent<ChatEventData>) => {
   // Do something with the event
});
Copy

Assignment

sdk.onChatEvent(ChatEvent.ASSIGNED_AGENT_CHANGED, (event) => {
    const assignee = event.detail.data.inboxAssignee;
    const agentName = `${assignee?.firstName ?? ''} ${assignee?.surname ?? ''}`.trim();
});
Copy

Socket events

Socket events documentation