Digital SDK de clavardage Web

SDK : GitHub

Référence API : GitHub Pages

Exemple d'application : GitHub

Progiciel NPM : npmjs.com

Le SDK de clavardage Web vous permet de créer votre propre application de clavardage numérique, ou d’ajouter le clavardage numérique à une application Web existante. Il vous 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 messagerie synchrone et asynchrone. Vous pouvez également configurer la messagerie à fil 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 multifilsClosed 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 permet de mieux contrôler NiCE CXone sur votre site Web. Il vous permet d’éviter certaines limitations techniques de certains sites Web. Par exemple, il se peut que votre site n’autorise pas le code externe, ce qui pourrait empêcher le clavardage numérique natif NiCE CXone de fonctionner.

Le SDK prend en charge les fonctionnalités suivantes :

  • Messagerie de clavardage Digital
  • OAuth2.0 pour l’autorisation
  • Champs d’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 saisie, de message vu et de message livré
  • Messages Système comme 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 est écrit en TypeScript 4.9+. Vous devez également utiliser un bundler like webpack or Create React App d’application personnalisée.

Ressources SDK

Le haut de cette page ou la liste déroulante en dessous fournissent des liens vers les diverses ressources du SDK.

Vos développeurs peuvent obtenir le SDK sur GitHub. Le référentiel contient un fichier LISEZ-MOI qui aide le développeur à démarrer. Elle contient également la documentation pour les Événements et la référence API. La référence API, plus conviviale, est hébergée séparément sur github.io.

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

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

SDK : GitHub

Référence API : GitHub Pages

Exemple d'application : GitHub

Progiciel NPM : npmjs.com

Termes clés

Terme Détails
Fil de discussion Une conversation au sein de l'application de clavardage. 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 de discussion. Chaque message consécutif dans la conversation est ajouté au fil de discussion. Les fils de discussion sont des objets qui contiennent chaque message. Les messages sont structurés par l'auteur du message. Un threadId identifie une conversation entière, et tous les messages au sein d'une conversation possèdent un ID de message. Un fil de discussion se termine lorsque la conversation se termine.
Fil unique Une conception d'application où le contact ne peut avoir qu'une seule conversation à la fois.
Canal de messagerie (multifils) Un canal asynchrone où un client peut tenir plusieurs conversations de longue durée à la fois. Le SDK expose ici getThreadList(), la dénomination des fils de discussion 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 pourriez avoir un canal de messagerie WhatsApp en temps réel. Le SDK mobile vous permet d'ajouter un canal de messagerie de clavardage à votre application mobile. Un canal est créé dans la plateforme NiCE CXone. Cela détermine les paramètres du canal ainsi que l'ID du canal. Vous utilisez cet ID pour initier le canal de clavardage lorsqu'un utilisateur de l'application ouvre le clavardage.
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 de contact Digital > Clavardage > Initialisation & Test).
BrandId Ceci est comme un ID de tenantClosed 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). Il est utilisé pour initialiser le clavardage. Vous pouvez le trouver dans les paramètres du canal de clavardage dans NiCE CXone (ACD > Digital > Points de contact Digital > Clavardage > Initialisation & Test).
CustomerId L'id unique de l'utilisateur final du clavardage. Le SDK crée cet ID lorsque le clavardage 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 OAuth configuré, cet ID est différent pour chaque appareil; l'ID devient comme une connexion invité.
Région ou Environnement L'emplacement dans le monde où votre déploiement NiCE CXone est hébergé. Les options sont : Australie (AU1), Canada (CA1), Europe (EU1), Japon (JP1), Amérique du Nord (NA1) ou Royaume-Uni (UK1). Le développeur doit utiliser la même région où votre système NiCE CXone est hébergé, sinon la connexion de clavardage est rejetée.
Contact, Client et utilisateur Ces termes font tous référence à 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 êtes susceptible de voir les termes client et utilisateur.
NiCE CXone La plateforme centrale où vous gérez et accédez à tous les outils d'expérience client qu'offre NiCE CXone. Selon les fonctionnalités de clavardage que vous souhaitez offrir 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 ou compte dans CXone, identifié par un ID de marque numérique. Toute la configuration de clavardage se trouve sous une marque.
Canal Livechat (session unique) Une session synchrone, acheminée par un agent. Le clavardage doit être démarré explicitement (startChat()) et peut être terminé (endChat()), et le client peut attendre dans une file d'attente. Le SDK retourne un LivechatThread pour ces canaux.
Fil de discussion Une conversation au sein d'un canal, identifiée par un id du fil. Elle contient l'historique des messages et constitue votre point d'accès principal pour l'envoi et la réception des messages.
Contact (aussi appelé cas) Une interaction unique acheminée, créée à partir d'un fil — l'unité qu'un agent prend réellement en charge. Un même fil peut donner lieu à plusieurs contacts au cours de sa durée de vie (par exemple, un nouveau contact chaque fois que le client reprend contact après une fermeture).
Message Un seul élément dans un fil — texte, pièce jointe ou contenu enrichi — rédigé par le client ou un agent.
Agent Une personne (ou un robot) du côté de CXone qui prend en charge le contact. L'attribution de l'agent et la frappe apparaissent sous forme d'événements.
Visiteur / visite Des identifiants d'analyse légers pour la personne qui navigue (identifiant du visiteur) et sa session de navigation actuelle (identifiant de la visite). Ils sont générés automatiquement pour vous si vous ne les fournissez pas et sont principalement utilisés pour le clavardage proactif et l'analyse.

Conditions préalables

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

  • environnement d’exécution ES2022. Le SDK s’appuie sur les API standard du navigateur : WebSocket, EventSource, crypto, Intl, Promise, EventTarget, CustomEvent, JSON, Date.

  • Un empaqueteur 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 commencer à développer

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

  • Disposez-vous d’un compte d’administrateur et d’un compte d’agent dans NiCE CXone? Un administrateur peut-il vous aider à configurer les fonctionnalités nécessaires dans la NiCE CXoneplateforme?
  • Avez-vous déjà des canaux de clavardage, ou souhaitez-vous en créer un nouveau?
  • Souhaitez-vous proposer des conversations à un ou plusieurs fils?
  • Quels types de messages enrichis souhaitez-vous configurer? Quels sont les cas d’utilisation où vous pouvez tirer parti de ces messages interactifs?
  • Utiliserez-vous des actions proactives, comme des fenêtres contextuelles ou des messages de bienvenue?

Initialiser correctement le clavardage

Vos développeurs doivent connecter votre application à NiCE CXone pour amorcer la communication bidirectionnelle. Cela crée une connexion WebSocket. Les Développeurs peuvent le faire en appelant await sdk.connect(). Assurez-vous de demander à vos développeurs de le faire uniquement 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'exportation par défaut et créez une instance avec votre marque, votre canal et votre région. Les options storageet cacheStorage sont 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).

Configuration minimale (sans persistance)

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

const sdk = new ChatSdk({

brandId: 1234,

channelId: 'chat_abcd1234-...',

customerId: 'your-customer-id',

environment: EnvironmentName.EU1,

storage: null,

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-...',

customerId: 'your-customer-id',

environment: EnvironmentName.EU1,

storage: window.localStorage,

cacheStorage: new CacheStorage(window.localStorage),

});

Remarques sur les Options requises

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

  • customerId — 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 (p. ex. 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() se résout à true lorsqu'il crée la connexion et à false si une connexion existe déjà — il n'ouvre jamais un second socket. Appelez-le une fois par durée de vie de la page; le SDK prend en charge la reconnexion, le heartbeat et le renouvellement du jeton à partir de ce moment.

Important : appelez connect() Uniquement 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 du canal et la disponibilité sans ouvrir de connexion — utile pour décider s'il faut afficher le widget de clavardage.

const info = await sdk.getChannelInfo();

const { status } = await sdk.getChannelAvailability(); // 'en ligne' | 'hors ligne'

getChannelInfo() retourne un objet ChannelInfo avec :

  • isLiveChat— indique si ce canal est un canal de clavardage en direct (livechat).

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

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

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

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

Un fil de discussion est votre poignée sur une conversation. Obtenez-le avec getThread(threadId) — synchrone, sans demande réseau. Retourne Thread pour les canaux de messagerie ou LivechatThread pour le clavardage en direct. Appelez uniquement après que connect()se résout.

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 (facultatif).

const recovered = await thread.recover();

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

// Envoyer un message texte.

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

Remarques

  • onThreadEvent(type, handler) renvoie une fonction de désinscription. Restreignez event.detail à l'aide de gardes de type avant de lire les données.

  • recover() charge l'état du fil de discussion à partir du serveur. Enveloppez-le dans try/catch — il rejette avec ThreadRecoverFailedError si le fil de discussion 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,

storage: null,

cacheStorage: null,

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

});

// 2. Vérifier la disponibilité avant d'afficher l'interface utilisateur.

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

if (status === 'offline') {

console.log('Aucun agent disponible pour le moment.');

}

// 3. Connectez-vous une seule 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)) {

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

}

},

);

// 5. Envoyez le premier message.

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

}

startChat();

Quoi de neuf