Investec Platform Plugins

Appearance

Livechat ​

@investec/plugins-livechat wraps the NICE CXone web SDK behind a smaller browser-friendly API for starting chat, recovering threads, sending messages, and listening for chat events.

Package ​

sh
npm install --save @investec/plugins-livechat

Public contract ​

Import the LiveChat class:

ts
import { LiveChat } from '@investec/plugins-livechat';

Its main methods are:

  • setUpChat(brandId, channelId)
  • startChat(authToken)
  • sendMessage(message)
  • handleTyping(timeout)
  • endChat()
  • resetSession()
  • getRecoveredMessages()
  • loadMoreMessagesFromSDK()
  • checkForChannelAvailability()
  • setUpEventListeners()
  • removeEventListeners()
  • getSessionState()

Integration pattern ​

ts
import { LiveChat } from '@investec/plugins-livechat';

const liveChat = new LiveChat();

await liveChat.setUpChat(brandId, channelId);
await liveChat.startChat(authToken);

liveChat.setUpEventListeners();
await liveChat.sendMessage('Hello');

Call setUpChat(...) before startChat(...). The class validates its session state and throws if methods are called in the wrong order.

Runtime behaviour ​

The wrapper:

  • creates a NICE ChatSdk instance with live-chat mode enabled
  • connects with the supplied auth token
  • reuses or recovers a stored thread when possible
  • stores the recovered thread ID in local storage under LIVECHAT-THREAD-ID
  • emits document-level custom events for agent typing, agent connection, message creation, and contact-status changes

Browser events ​

After setUpEventListeners(), the plugin can dispatch:

  • new-message-from-agent
  • agent-typing
  • agent-connected
  • chat-status-changed

These events are emitted on document.

Session-state model ​

The wrapper manages these states internally:

  • disconnected
  • connecting
  • connected
  • recovering
  • resolved
  • error

Use getSessionState() if the host UI needs to inspect the current state.

How consumers extend it ​

Consumers extend this package by owning the chat UI and reacting to the wrapper's events and methods.

Typical consumer behaviour includes:

  • rendering chat state from getSessionState();
  • listening for document-level agent and message events;
  • deciding when to call handleTyping(...), sendMessage(...), and loadMoreMessagesFromSDK();
  • mapping recovered or loaded messages into an app-specific transcript model.

Change the package when the NICE integration contract changes, such as auth, thread recovery, provider event handling, or shared error semantics.

Extension example: own the chat transcript in consumer UI state ​

ts
import { LiveChat } from '@investec/plugins-livechat';

type ChatMessage = {
  author: string;
  text: string;
  timestamp: string;
};

const liveChat = new LiveChat();
const transcript: ChatMessage[] = [];

document.addEventListener('new-message-from-agent', (event) => {
  const detail = (event as CustomEvent<ChatMessage>).detail;
  transcript.push(detail);
});

document.addEventListener('chat-status-changed', (event) => {
  const status = (event as CustomEvent<string>).detail;
  console.log('Chat status changed:', status);
});

export async function startSupportChat(authToken: string) {
  await liveChat.setUpChat(123456, 'my-channel-id');
  await liveChat.startChat(authToken);
  liveChat.setUpEventListeners();
}

export async function sendSupportMessage(message: string) {
  await liveChat.sendMessage(message);
}

Consumer notes ​

  • startChat(...) only accepts an auth token in the current implementation.
  • endChat() and resetSession() both clear the cached thread ID and SDK state.
  • getRecoveredMessages() and loadMoreMessagesFromSDK() normalise NICE message objects into simpler author/text/timestamp records for UI consumption.
  • This package is a standalone integration wrapper; it does not depend on the other builder plugins in this repo.