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 ​

Note — approved exception: livechat is the one plugin in this repository with an approved direct-installation contract for consumer/feature applications, via the shared global-navigation library pattern used by consumer apps. This is a deliberate, documented exception to the platform-only default that applies to every other plugin. See Plugin change governance for the general rule.

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

The platform owns installation of released plugin versions. A consuming team normally contributes shared provider logic in this repository and then asks the platform team to adopt the published version. Direct feature use requires an explicit integration contract.

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

Extend the shared plugin ​

Add shared NICE behaviour in livechat/src/lib/livechat.ts and expose it from livechat/src/index.ts. For a new provider operation or event:

  1. confirm that the NICE SDK supports the operation;
  2. define its allowed session states;
  3. preserve setup, connection, recovery, and reset ordering;
  4. normalise provider data before exposing it;
  5. add listener cleanup and tests for repeated setup and teardown;
  6. document the browser event or method contract.

Contact the Web Platform team before changing authentication, secure-session mode, provider environment, thread persistence, token handling, document event names, or the third-party SDK dependency.

Consumer notes ​

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