NICE CXone Chat Web SDK

• Official SDK Documentation
• NPM package
• Sample Web App

Requirements

• TypeScript 4.9
• Runtime: ES2022 (WebSocket, Intl, Promise, EventTarget, CustomEvent, JSON, Date, 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

// Initialize Chat SDK with required options
const sdk = new ChatSdk({
  brandId: 123,
  channelId: 'my-channel-id',
  customerId: 'customer-id',
  environment: EnvironmentName.EU1
});
Copy

Authorization

await sdk.authorize()
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 = await sdk.getThread('thread-id');
// Optionally recover a thread state (messages) from the server
const threadRecoveredData = await thread.recover();
console.log(threadRecoveredData.messages);
Copy

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

const loadMoreMessageResponse = await thread.loadMoreMessages();
console.log(loadMoreMessageResponse.data.messages);
Copy

Mark messages as read

await thread.lastMessageSeen();
Copy

Livechat

Livechat channel needs to call startChat() method first to start the chat. Customers might end the chat by calling endChat() method.

await thread.startChat();
Copy

Get position in queue:

sdk.onChatEvent(ChatEvent.SET_POSITION_IN_QUEUE, (event) => {
    if (isSetPositionInQueuePayload(event.detail)) {
        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

Attachements

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_STOPPED, (event: CustomEvent<ChatEventData>) => {
   // Do something with the event
});
Copy

Assignemnt

sdk.onChatEvent(ChatEvent.ASSIGNED_AGENT_CHANGED, (event: CustomEvent<ChatEventData>) => {
    const agentName = parseAgentName((event.detail.data as AssignedAgentChangedData).inboxAssignee);
});
Copy

Socket events

Socket events documentation