Digital SDK web de chat

SDK: GitHub

Referencia de API: GitHub Páginas

Aplicación de muestra: GitHub

Paquete NPM: npmjs.com

El SDK web de chat le permite crear su propia aplicación de conversación digital, o agregar conversación digital a una aplicación web existente. Permite usar la infraestructura digital de NiCE CXone en una interfaz de usuario de su elección. Este es un SDK basado en JavaScript que admite ambos LiveChat y Chat Messaging: mensajería síncrona y asíncrona. También puede configurar la mensajería de unoClosed En una aplicación de un solo hilo, cada contacto tiene un hilo de chat que maneja cualquier interacción que tenga con su organización. o varios hilosClosed En una aplicación de subprocesos múltiples, los contactos pueden crear tantos subprocesos como deseen para discutir nuevos temas. Estos subprocesos pueden estar activos al mismo tiempo.. Este SDK le brinda más control sobre NiCE CXone en su sitio web. Ayuda a evitar ciertas limitaciones técnicas que tienen algunos sitios web. Por ejemplo, es posible que su sitio no permita código externo, lo cual podría impedir que se ejecute la conversación digital nativa de NiCE CXone.

El SDK admite las siguientes funciones:

  • mensajería de chat Digital
  • OAuth2.0 para autorización
  • Identificación de contacto y campos personalizados
  • Lista de hilos y recuperación de hilos
  • archivos adjuntos
  • Mensajes enriquecidos
  • indicadores de escritura, mensaje visto y mensaje entregado
  • mensajes del Sistema, como eventos de estado de casos o eventos de asignación
  • eventos de posición en cola

  • Acciones proactivas (ventanas emergentes, mensajes de bienvenida)

Este SDK está escrito en TypeScript 4.9+. También debe usar una aplicación personalizada bundler like webpack or Create React App.

Recursos del SDK

La parte superior de esta página o el menú desplegable que aparece a continuación proporcionan enlaces a los distintos recursos del SDK.

Sus desarrolladores pueden obtener el SDK en GitHub. El repositorio tiene un LÉAME que ayuda al desarrollador a empezar. También contiene documentación para eventos y la referencia de la API. La referencia de API más amistosa para el usuario está hospedada por separado a través de github.io.

También puede consultar la aplicación de muestra. Esto le permite probar el chat y revisar el código fuente correspondiente.

Los desarrolladores importan el SDK como un paquete NPM. La entrada del paquete en npmjs.com contiene todo el mismo contenido e instrucciones para configurar y construir con el SDK.

SDK: GitHub

Referencia de API: GitHub Páginas

Aplicación de muestra: GitHub

Paquete NPM: npmjs.com

Términos clave

Término Detalles
Hilo Una conversación dentro de la aplicación de chat. El primer mensaje enviado por el agente o el contactoClosed La persona que interactúa con un agente, IVR o bot en su centro de contacto. inicia un hilo. Cada mensaje consecutivo de la conversación se agrega al hilo. Los hilos son objetos que contienen cada mensaje. Los Mensajes se estructuran según el autor del Mensaje. Un threadId identifica una conversación completa, y todos los mensajes dentro de una conversación tienen un ID de mensaje. Un hilo termina cuando finaliza la conversación.
Un solo hilo Un diseño de aplicación en el que el contacto solo puede tener una conversación a la vez.
Canal de Messaging (multihilo) Un canal asíncrono en el que un cliente puede mantener varias conversaciones de larga duración al mismo tiempo. Aquí, el SDK expone getThreadList(), la asignación de nombres a los hilos y el archivado.
Canal En el contexto de Digital Experience (DX), el canal se refiere al tipo de mensajería o la plataforma utilizada para la comunicación. Por ejemplo, podría tener un canal de mensajería en tiempo real de WhatsApp. El Mobile SDK le permite agregar un canal de mensajería de chat a su aplicación móvil. Un canal se crea en la plataforma de NiCE CXone. Esto determina la configuración del canal junto con un ID de canal. Usted utiliza este ID para iniciar el canal de chat cuando un usuario de la aplicación abre el chat.
ChannelId El id del canal de conversación digital creado en la sección Digital de NiCE CXone. Puede encontrar esto en la configuración del canal de chat en NiCE CXone (ACD > Digital > Points of Contact Digital > Chat > Initialization & Test).
BrandId Esto es como un id de abonado para Digital Experience (DX). Se utiliza para inicializar el chat. Puede encontrar esto en la configuración del canal de chat en NiCE CXone (ACD > Digital > Points of Contact Digital > Chat > Inicialización y Prueba).
CustomerId The unique ID of the chat end user. The SDK creates this ID when the chat is initialized. If you have OAuth set up, this ID stays the same for each contact across all their devices. If you do not have OAuth set up, this ID is different for each device; the ID becomes like a guest login.
Región o Entorno La ubicación en el mundo donde está alojada su implementación de NiCE CXone. Puede ser: Australia (AU1), Canadá (CA1), Europa (EU1), Japón (JP1), Norteamérica (NA1) o Reino Unido (UK1). El desarrollador debe utilizar la misma región en la que su sistema NiCE CXone está alojado, de lo contrario se rechazará la conexión al chat.
Contacto, Cliente y Usuario Estos términos hacen referencia al usuario final de la aplicación móvil. La ayuda en línea suele utilizar el término contacto. En la documentación del SDK y en los comentarios de código, es probable que vea cliente y usuario.
NiCE CXone La plataforma principal donde usted administra y accede a todas las herramientas de experiencia del cliente que NiCE CXone ofrece. Dependiendo de las funciones de chat que desee ofrecer en su aplicación móvil, un administrador con los permisos de cuenta de usuario necesarios debe completar varias tareas de configuración en NiCE CXone.
Digital Experience (DX) La sección de NiCE CXone donde puede administrar todo lo relacionado con digital channels.
Marca Su empresa/cuenta en CXone, identificada por un brandId numérico. Toda la configuración de chat se encuentra bajo una marca.
Canal Livechat (sesión única) Una sesión síncrona, enrutada por agente. El chat debe iniciarse explícitamente (startChat()) y se puede finalizar (Chat finalizado()), y el cliente puede esperar en una cola. El SDK devuelve un LivechatThread para estos canales.
Hilo Una conversación dentro de un canal, identificada por un id de hilo. Contiene el historial de mensajes y es su control principal para enviar y recibir mensajes.
Contacto (también conocido como caso) Una interacción enrutada única creada a partir de un hilo, es decir, la unidad que el agente realmente recibe y procesa. Un hilo puede generar múltiples contactos a lo largo de su ciclo de vida (por ejemplo, un contacto nuevo cada vez que el cliente vuelve a interactuar después del cierre).
Mensaje Un elemento individual en una conversación —texto, un adjunto o contenido enriquecido— creado por el cliente o un agente.
Agente Un ser humano (o bot) del lado de CXone que atiende el contacto. La asignación y el tipo de Agente aparecen como eventos.
Visitante / visita Identificadores de analíticas ligeros para la persona que está navegando (visitorId) y su sesión de navegación actual (visitId). Se generan para usted si no los proporciona, y son relevantes principalmente para el chat proactivo y las analíticas.

Prerrequisitos

  • TypeScript 4.9+ (el SDK incluye sus propias definiciones de tipos).

  • Tiempo de ejecución de ES2022. El SDK depende de API estándar del navegador: WebSocket, EventSource, crypto, Intl, Promise, EventTarget, CustomEvent, JSON, Date.

  • Un empaquetador de módulos (webpack, Vite, Create React App, etc.). El SDK es distribuido como módulos ES y está diseñado para empaquetarse en su aplicación.

  • Una aplicación personalizada (usted crea la UI).

Antes de Comenzar a Desarrollar

Considere los siguientes elementos antes de crear usando el SDK móvil:

  • ¿Dispone de una cuenta de administrador y de agente en NiCE CXone? ¿Puede un administrador ayudarle a configurar las funciones necesarias en la plataforma de NiCE CXone?
  • ¿Dispone de canales de chat o quiere crear uno nuevo?
  • ¿Desea ofertar conversaciones de subproceso único o de múltiples subprocesos?
  • Cuáles tipos de mensajes enriquecidos desea configurar? ¿En qué casos puede aprovechar estos mensajes interactivos?
  • ¿Usará acciones proactivas como ventanas emergentes o mensajes de bienvenida?

Inicializar el chat correctamente

Sus desarrolladores deben conectar su aplicación a NiCE CXone para comenzar la comunicación en ambos sentidos. Esto crea una conexión WebSocket. Los Desarrolladores pueden hacerlo llamando a await sdk.connect(). Asegúrese de indicarles a sus desarrolladores que lo hagan solo para conversaciones de chat activo. Esto garantiza que el WebSocket se ejecute únicamente cuando sea necesario.

Instalación

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

Initialización

Importe la exportación predeterminada y cree una instancia con su marca, canal y región. storagey cacheStorage Son opciones obligatorias; pase null para deshabilitar la persistencia y el almacenamiento en caché, o pase implementaciones reales para habilitarlos (consulte a continuación).

Setup mínimo (Sin Persistencia)

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

const sdk = new ChatSdk({

brandId: 1234,

channelId: 'chat_abcd1234-...',

Identificación del cliente: 'your-customer-id',

environment: EnvironmentName.EU1,

storage: null,

cacheStorage: null,

});

Configuración de producción (con persistencia)

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

const sdk = new ChatSdk({

brandId: 1234,

channelId: 'chat_abcd1234-...',

Identificación del cliente: 'your-customer-id',

environment: EnvironmentName.EU1,

storage: window.localStorage,

cacheStorage: new CacheStorage(window.localStorage),

});

Notas sobre las Opciones requeridas

  • brandId y channelId: identifican el canal (cree un canal de chat en CXone para obtenerlos).

  • customerId — no es obligatorio a menos que use sesiones seguras (securedSession), en cuyo caso la plataforma establece la identidad. Consulte authentication.md.

  • Entorno: selecciona la región de CXone (por ejemplo, EU1, NA1, AU1). Si se elige la región incorrecta, el SDK se comunicará con la puerta de enlace equivocada.

Conectando

El SDK no se conecta automáticamente. Abra el WebSocket explícitamente:

await sdk.connect();

connect() se resuelve en true cuando crea la conexión y en false si ya existe una, nunca abre un segundo socket. Llámelo una vez por cada ciclo de vida de la página; el SDK se encarga de la reconexión, el latido (heartbeat) y la renovación de tokens a partir de ese momento.

Importante: Solo llame a connect() para conversaciones de chat activo, de modo que el WebSocket se ejecute solo cuando sea necesario.

Inspección de la información del Canal

Puede consultar la configuración y la disponibilidad del canal sin abrir una conexión, lo cual resulta útil para decidir si debe mostrar el widget de chat.

const info = await sdk.getChannelInfo();

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

getChannelInfo() devuelve un objeto ChannelInfo con:

  • isLiveChat: indica si este es un canal de chat en vivo.

  • Configuración — restricciones de carga de archivos (settings.fileRestrictions) e indicadores de funciones (settings.features).

  • translations — cadenas localizadas para el idioma configurado.

Ambas llamadas también están disponibles como funciones independientes si necesita datos del canal antes de construir una instancia de SDK.

Abrir un Hilo y Enviar/Recibir Mensajes

Un Thread es su controlador para una conversación. Obténgalo con getThread(threadId), de forma sincrónica, sin solicitud de red. Devuelve Thread para los canales de mensajería o LivechatThread para el chat en vivo. Llame solo después de que se resuelva 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');

// Escuche los mensajes entrantes ANTES de enviar.

thread.onThreadEvent(

ChatEvent.MESSAGE_CREATED,

(event: CustomEvent<ChatEventData>) => {

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

const { message } = event.detail.data;

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

},

);

// Cargar historial existente (opcional).

const recovered = await thread.recover();

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

Enviar un mensaje de texto.

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

Notas

  • onThreadEvent(type, handler) devuelve una función de anulación de registro. Reduzca event.detail con protectores de tipo (type guards) antes de leer los datos.

  • recover() carga el estado del hilo desde el servidor. Envuélvalo en try/catch: rechaza con ThreadRecoverFailedError si el hilo no existe.

  • Canales de Livechat: llame a await (thread as LivechatThread).startChat() antes de enviar mensajes.

Ejemplo Completo

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. Inicializar.

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. Verificar disponibilidad antes de mostrar la IU.

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

if (status === 'offline') {

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

}

// 3. Conectar una vez.

await sdk.connect();

// 4. Abra un hilo y escuche los mensajes.

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. Enviar el primer mensaje.

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

}

startChat();

Qué sigue