Digital SDK Chat Web

SDK : GitHub

Référence de l'API : GitHub Pages

Exemple d'application : GitHub

Progiciel NPM : npmjs.com

Le SDK Web de clavardage vous permet de créer votre propre application de clavardage numérique, ou d'ajouter le clavardage numérique à une application Web existante. Il permet d’utiliser l’infrastructure numérique NiCE CXone dans l’interface utilisateur de votre choix. Il s'agit d'un SDK basé sur JavaScript qui prend en charge à la fois LiveChat et Chat Messaging, à la fois la messagerie synchrone et asynchrone. Vous pouvez également le configurer pour mettre en place une messagerie uniqueClosed Dans une application à un seul thread, chaque contact dispose d’un seul thread de clavardage qui gère toute interaction qu’il a avec votre organisation. ou à fils multiplesClosed Dans une application multithread, les contacts peuvent créer autant de fils de discussion qu’ils le souhaitent pour discuter de nouveaux sujets. Ces fils peuvent être actifs en même temps.. Ce SDK vous offre plus de contrôle sur NiCE CXone sur votre site Web. Il vous aide à éviter certaines limitations techniques présentes sur certains sites web. Par exemple, votre site peut ne pas autoriser le code externe, ce qui pourrait empêcher l'exécution du clavardage numérique NiCE CXone natif.

Le SDK prend en charge les fonctionnalités suivantes :

  • Messagerie de chat Digital
  • OAuth2.0 pour l’autorisation
  • Identification des contacts et champs personnalisés
  • Liste des fils de discussion et récupération des fils de discussion
  • Pièces jointes
  • Messages enrichis
  • Indicateurs de frappe, de consultation des messages et de livraison des messages
  • Messages Système tels que les événements d’état de dossier ou les événements d’affectation
  • événements de position dans la File d’attente

  • Actions proactives (fenêtres contextuelles, messages de bienvenue)

Ce SDK a été écrit en TypeScript 4.9+. Vous devez également utiliser un bundler like webpack or Create React App personnalisé.

Ressources du SDK

Le haut de cette page ou la liste déroulante située en dessous comporte des liens vers les différentes ressources du SDK.

Vos développeurs peuvent obtenir le SDK sur GitHub. Le référentiel comporte un fichier README qui permet au développeur de commencer. Il contient également la documentation relative aux événements et la référence de l'API. La référence API la plus conviviale est hébergée séparément via github.io.

Vous pouvez également consulter l'application exemple. Elle vous permet d'essayer le chat et de consulter le code source correspondant.

Les développeurs importent le SDK en tant que package NPM. L’entrée du package sur npmjs.com contient le même contenu et les instructions de configuration et de création avec le SDK.

SDK : GitHub

Référence de l'API : GitHub Pages

Exemple d'application : GitHub

Progiciel NPM : npmjs.com

Termes clé

Terme Détails
Thread Une conversation au sein de l'application de chat. Le premier message envoyé par l’agent ou le contactClosed La personne qui interagit avec un agent, un SRVI ou un robot dans votre centre d’appels. commence un fil. Chaque message consécutif de la conversation est ajouté au fil. Les fils sont des objets qui contiennent chaque message. Les messages sont structurés par l’auteur du message. Un threadId identifie l’ensemble d’une conversation, et tous les messages appartenant à une conversation ont un ID de message. Un fil se termine lorsque la conversation se termine.
Fil unique Une conception d'application selon laquelle le contact ne peut avoir qu'une seule conversation à la fois.
Canal de messagerie (multi-thread) Canal asynchrone dans lequel un client peut tenir plusieurs conversations durables à la fois. Le SDK expose ici getThreadList(), la dénomination des threads et l'archivage.
Canal Dans le contexte de Digital Experience (DX), canal désigne le type de messagerie ou la plateforme utilisée pour la communication. Par exemple, vous pouvez avoir un canal WhatsApp de messagerie en temps réel. Le Mobile SDK vous permet d'ajouter un canal de messagerie de chat à votre application mobile. Un canal est créé dans la plateforme NiCE CXone. Ceci détermine les paramètres du canal ainsi qu'un ID de canal. Vous utilisez cet ID pour lancer le canal de chat lorsqu'un utilisateur de l'application ouvre le chat.
ChannelId L'ID du canal de clavardage numérique créé dans la Section Digital de NiCE CXone. Vous pouvez le trouver dans les paramètres du canal de clavardage dans NiCE CXone (ACD > Digital > Points of Contact Digital > Chat > Initialization & Test).
BrandId Il s'agit d'un identifiant similaire à un locataireClosed Regroupement organisationnel de haut niveau utilisé pour gérer le soutien technique, la facturation et les paramètres globaux de votre système NiCE CXone. pour Digital Experience (DX). Cela est utilisé pour initialiser le chat. Vous trouverez cela dans les paramètres du canal de chat dans NiCE CXone (ACD > Digital > Points of Contact Digital > Chat > Initialization & Test).
CustomerId L'id unique de l'utilisateur final du chat. Le SDK crée cet ID lorsque le chat est initialisé. Si vous avez OAuth configuré, cet ID reste le même pour chaque contact sur tous ses appareils. Si vous n'avez pas configuré OAuth, cet ID est différent pour chaque appareil ; l'ID devient alors comme une connexion invité.
Région ou Environnement Emplacement dans le monde où votre déploiement NiCE CXone est hébergé. Cela peut être : Australie (AU1), Canada (CA1), Europe (EU1), Japon (JP1), Amérique du Nord (NA1) ou Royaume-uni (UK1). Le développeur doit utiliser la région où votre système NiCE CXone est hébergé, sinon la connexion de chat est rejetée.
Contact, Client et Utilisateur Ces termes désignent tous l'utilisateur final de l'application mobile. L’aide en ligne utilise généralement le terme contact. Dans la documentation du SDK et les commentaires du code, vous verrez généralement les termes client et utilisateur.
NiCE CXone La plateforme centrale où vous gérez et accédez à tous les outils d'expérience client proposés par NiCE CXone. Selon les fonctionnalités de chat que vous souhaitez proposer dans votre application mobile, un administrateur disposant des autorisations de compte utilisateur nécessaires doit effectuer plusieurs tâches de configuration dans NiCE CXone.
Digital Experience (DX) La section de NiCE CXone où vous pouvez gérer tout ce qui concerne digital channels.
Marque Votre entreprise/compte dans CXone, identifié par un ID de marque numérique. Toute la configuration du chat se trouve sous une marque.
Canal Livechat (session unique) Il s'agit d'une session synchrone, acheminée vers un agent. Le chat doit être démarré explicitement (startChat()) et peut être terminé (endChat()), et le client peut attendre dans une file d'attente. Le SDK renvoie un LivechatThread pour ces canaux.
Thread Une conversation au sein d'un canal, identifiée par un id du fil. Elle contient l'historique des messages et constitue votre principal moyen d'envoyer et de recevoir des messages.
Contact (alias cas) Une interaction acheminée unique créée à partir d'un fil de discussion — l'unité qu'un agent prend réellement en charge et traite. Un même fil de discussion peut générer plusieurs contacts au cours de son cycle de vie (par exemple, un nouveau contact chaque fois que le client reprend contact après une clôture).
Message Un seul élément d'un fil de discussion — texte, pièce jointe ou contenu enrichi — rédigé par le client ou un Agent.
Agent Un humain (ou un bot) du côté de CXone qui traite le contact. L'affectation de l'Agent et la frappe apparaissent sous forme d'événements.
Visiteur / visite Identifiants analytiques légers pour la personne qui navigue (identifiant du visiteur) et sa session de navigation actuelle (visitId). Ils sont générés pour vous si vous ne les fournissez pas et sont principalement importants pour le chat proactif et l'analytique.

Conditions préalables

  • TypeScript 4.9+ (le SDK fournit ses propres définitions de type).

  • Runtime ES2022. Le SDK s'appuie sur des API de navigateur standard : WebSocket, EventSource, crypto, Intl, Promise, EventTarget, CustomEvent, JSON, Date.

  • Un bundler de modules (webpack, Vite, Create React App, etc.). Le SDK est distribué sous forme de modules ES et est destiné à être empaqueté dans votre application.

  • Une application personnalisée (vous créez l'interface utilisateur).

Avant de Démarrer le développement

Tenez compte des éléments suivants avant d'utiliser le SDK mobile :

  • Disposez-vous à la fois d’un compte administrateur et d’un compte agent dans NiCE CXone ? Un administrateur peut-il vous aider à configurer les fonctionnalités nécessaires dans la NiCE CXoneplateforme ?
  • Disposez-vous de canaux de chat ou voulez-vous en créer un ?
  • Souhaitez-vous proposer une offre de conversations à fil unique ou à fils multiples ?
  • Quels types de messages enrichis souhaitez-vous configurer ? Quels sont les cas d’utilisation où vous pouvez exploiter ces messages interactifs ?
  • Allez-vous utiliser des actions proactives telles que des fenêtres contextuelles ou des messages de bienvenue ?

Initialiser correctement le chat

Vos développeurs doivent connecter votre application à NiCE CXone pour commencer la communication dans les deux sens. Cela crée une connexion WebSocket. Les Développeurs peuvent le faire en appelant await sdk.connect(). Veillez à indiquer à vos développeurs de ne le faire que pour les conversations de clavardage actif. Cela garantit que le WebSocket ne s'exécute que lorsque cela est nécessaire.

Installation

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

Initialisation

Importez l'export par défaut et créez une instance avec votre marque, votre canal et votre région. storage et cacheStorage sont des Options requises — transmettez null pour désactiver la persistance et la mise en cache, ou transmettez de véritables implémentations pour les activer (voir ci-dessous).

Installer minimal (sans persistance)

import ChatSdk, { EnvironmentName } from '@nice-devone/nice-cxone-chat-web-sdk';

const sdk = new ChatSdk({

ID de marque: 1234,

channelId: 'chat_abcd1234-...',

customerId: 'your-customer-id',

environment: EnvironmentName.EU1,

storage: null,

```html cacheStorage: null, ```

});

Configuration de production (avec persistance)

import ChatSdk, { CacheStorage, EnvironmentName } from '@nice-devone/nice-cxone-chat-web-sdk';

const sdk = new ChatSdk({

brandId: 1234,

channelId: 'chat_abcd1234-...',

N ° de client: 'your-customer-id',

environment: EnvironmentName.EU1,

storage: window.localStorage,

cacheStorage: new CacheStorage(window.localStorage),

});

Notes sur les Options requises

  • ID de marque et ID de canal — identifient le canal (créez un canal de chat dans CXone pour les obtenir).

  • N ° de client — requis sauf si vous utilisez des sessions sécurisées (securedSession), auquel cas la plateforme établit l'identité. Voir authentication.md.

  • Environnement — sélectionne la région CXone (par exemple, EU1, NA1, AU1). Si vous choisissez la mauvaise région, le SDK communique avec la mauvaise passerelle.

Connexion

Le SDK ne se connecte pas automatiquement. Ouvrez le WebSocket explicitement :

await sdk.connect();

connect() est résolu en true lorsqu'il crée la connexion et en false si une connexion existe déjà — il n'ouvre jamais un deuxième socket. Appelez-le une fois par durée de vie de la Page ; le SDK gère ensuite la reconnexion, le signal de présence (heartbeat) et le renouvellement du jeton.

Important : Appelez Uniquement connect() pour les conversations de clavardage actif, afin que le WebSocket ne s'exécute que lorsque cela est nécessaire.

Inspection des informations sur le Canal

Vous pouvez interroger la configuration et l'availability du canal sans ouvrir de connexion, ce qui est utile pour décider s'il convient d'afficher le widget de chat.

const info = await sdk.getChannelInfo();

const { status } = await sdk.getChannelAvailability(); // 'online' | 'offline'

getChannelInfo() renvoie un objet ChannelInfo avec :

  • isLiveChat— indique s'il s'agit d'un canal de chat en direct.

  • Paramètres utilisateur — restrictions de téléversement de fichiers (settings.fileRestrictions) et indicateurs de fonctionnalités (settings.features).

  • translations — chaînes localisées pour la langue configurée.

Les deux appels sont également disponibles sous forme de fonctions autonomes si vous avez besoin des données de canal avant de construire une instance de SDK.

Ouverture d'un Thread et envoi/réception de Messages

Un Thread est votre identifiant pour une conversation. Obtenez-le avec getThread(threadId) — synchrone, sans requête réseau. Renvoie Thread pour les canaux de messagerie ou LivechatThread pour le livechat. Appelez-le uniquement après la résolution de connect().

import { ChatEvent, isMessageCreatedEvent } from '@nice-devone/nice-cxone-chat-web-sdk';

import type { ChatEventData } from '@nice-devone/nice-cxone-chat-web-sdk';

const thread = sdk.getThread('my-thread-id');

// Écoutez les messages entrants AVANT l'envoi.

thread.onThreadEvent(

ChatEvent.MESSAGE_CREATED,

(event: CustomEvent<ChatEventData>) => {

if (!isMessageCreatedEvent(event.detail)) return;

const { message } = event.detail.data;

console.log('New message:', message);

},

);

// Charger l'historique existant (en option).

```html const recovered = await thread.recover(); ```

console.log('Recovered messages:', recovered.messages);

Envoyer un message texte.

await thread.sendTextMessage('Hello! I need some help.');

Notes

  • onThreadEvent(type, handler) retourne une fonction de désinscription. Affinez event.detail avec des gardes de type (« type guards ») avant de lire les données.

  • recover() charge l'état du thread à partir du serveur. Encadrez-le dans un bloc try/catch : il est rejeté avec ThreadRecoverFailedError si le thread n'existe pas.

  • Canaux Livechat : appelez await (thread as LivechatThread).startChat() avant d'envoyer des messages.

Exemple complet

import ChatSdk, {

ChatEvent,

EnvironmentName,

generateId,

isMessageCreatedEvent,

} from '@nice-devone/nice-cxone-chat-web-sdk';

import type { ChatEventData } from '@nice-devone/nice-cxone-chat-web-sdk';

async function startChat() {

1. Initialiser.

const sdk = new ChatSdk({

brandId: 1234,

channelId: 'chat_abcd1234-...',

customerId: generateId(),

environment: EnvironmentName.EU1,

```html storage: null, ```

cacheStorage: null,

onError: (error) => console.error('Chat SDK error:', error),

});

// 2. Vérifiez la disponibilité avant d'afficher l'UI.

const { status } = await sdk.getChannelAvailability();

if (status === 'offline') {

console.log('No agents available right now.');

}

// 3. Connecter une fois.

await sdk.connect();

// 4. Ouvrez un thread et écoutez les messages.

const thread = sdk.getThread(generateId());

thread.onThreadEvent(

ChatEvent.MESSAGE_CREATED,

(event: CustomEvent<ChatEventData>) => {

if (isMessageCreatedEvent(event.detail)) {

```javascript console.log('Message:', event.detail.data.message); ```

}

},

);

// 5. Envoyer le premier message.

await thread.sendTextMessage('Hi there!');

}

startChat();

Étapes suivantes