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

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';

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,
});

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,
});

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()

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()

Channel Availability Info

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

await sdk.getChannelAvailability()

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);

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

Send a message

await thread.sendTextMessage('Message text');

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);
});

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);
}

Mark messages as read

await thread.lastMessageSeen();

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();

Get position in queue:

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

Multi-thread

Get list of threads

const threads = await sdk.getThreadList();

Load metadata

const metadata = await thread.getMetadata();

Archive thread

await thread.archive();

Set thread name

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

Attachments

await thread.sendAttachments(fileList);

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();

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
});

Assignment

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

Socket events

Socket events documentation