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

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, crypto, etc.)
• Custom application bundler (webpack, create-react-app, etc.)

Quickstart

• Import the SDK into your project

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

• Login to your Brand and create a Chat Channel, setup their respective IDs in the SDK init (brandId, channelId)
• Connect your project to the CXone environment (environment)
• Fork the code sandbox and test your configuration
• 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

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

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

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

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

Mark messages as read

await thread.lastMessageSeen();

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

Get position in queue:

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

Attachements

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

Assignment

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

Socket events

Socket events documentation