Digital SDK da Web de bate-papo
SDK: GitHub ![]()
Referência de API: GitHub Páginas ![]()
Aplicativo de exemplo: GitHub ![]()
Pacote NPM: npmjs.com ![]()
O SDK da web para chat permite que você crie seu próprio aplicativo de chat digital ou adicione o chat digital a um aplicativo da web existente. Isso permite que você use a infraestrutura digital do NiCE CXone em uma UI de sua escolha. Este é um SDK baseado em JavaScript que oferece suporte tanto a LiveChat quanto a Chat Messaging—mensagens síncronas e assíncronas. Você também pode configurar mensagens single
Em um aplicativo de thread única, cada contato tem uma thread de chat que gerencia qualquer interação que ele tenha com a sua organização. ou multi-threaded
Em um aplicativo multithread, os contatos podem criar quantos threads quiserem para discutir novos tópicos. Esses threads podem estar ativos ao mesmo tempo.. Este SDK oferece mais controle sobre NiCE CXone em seu website. Isso ajuda você a evitar determinadas limitações técnicas que alguns sites têm. Por exemplo, o seu site pode não permitir código externo, o que poderia impedir a execução do NiCE CXone chat digital nativo.
O SDK suporta os seguintes recursos:
- mensagens de chat Digital
- OAuth2.0 para autorização
- Identificação de contato e campos personalizados
- Lista de threads e recuperação de threads
- Anexos
- mensagens enriquecidas
- Indicadores de digitação, mensagem vista e mensagem entregue
- mensagens do Sistema como eventos de status de caso ou eventos de atribuição
- eventos de posição na Fila DE espera
Ações proativas (pop-ups, mensagens de boas-vindas)
Este SDK é escrito em TypeScript 4.9+. Você também deve usar um
Recursos de SDK
A parte superior desta página ou o menu suspenso abaixo fornece links para os vários recursos do SDK.
Seus desenvolvedores podem obter o SDK do GitHub. O repositório tem um arquivo README que ajuda o desenvolvedor a começar. Ele também contém documentação para eventos
e a referência da API. A referência de API mais amigável é hospedada separadamente através do github.io.
Você também pode consultar o aplicativo de amostra. Isso permite que você experimente o chat e veja o código-fonte correspondente.
Os desenvolvedores importam o SDK como um pacote NPM. A entrada do pacote no npmjs.com contém todo o mesmo conteúdo e instruções para configuração e criação com o SDK.
Termos-chave
| Termo | Detalhes |
|---|---|
| Conversa | Uma conversa dentro do aplicativo de chat. A primeira mensagem enviada pelo agente ou contato |
| Single-thread | Um design de aplicativo em que o contato só pode ter uma conversa por vez. |
| Canal de mensagens (multithread) | Um canal assíncrono em que um cliente pode manter diversas conversas de longa duração simultaneamente. O SDK expõe getThreadList(), nomenclatura de threads e arquivamento aqui. |
| Canal | No contexto de Digital Experience (DX), canal refere-se ao tipo de mensagem ou à plataforma usada para comunicação. Por exemplo, você pode ter um canal de mensagens em tempo real do WhatsApp. O Mobile SDK permite que você adicione um canal de mensagens de chat ao seu aplicativo móvel. Um canal é criado na plataforma NiCE CXone. Isso determina as configurações do canal junto com um ID de canal. Você usa esse ID para iniciar o canal de chat quando um usuário do aplicativo abre o chat. |
| ChannelId | O ID do canal de chat digital criado na seção Digital de NiCE CXone. Você pode encontrar isso nas configurações do canal de chat em NiCE CXone (ACD > Digital > Points of Contact Digital > Chat > Initialization & Testar). |
| BrandId | This é como um ID de locatário |
| CustomerId | Id exclusivo do usuário final do chat. O SDK cria esse ID quando o chat é inicializado. Se você configurou o OAuth, esse ID permanece o mesmo para cada contato em todos os seus dispositivos. Se você não tem OAuth configurado, esse ID é diferente para cada dispositivo; o ID passa a funcionar como um login de convidado. |
| Região ou Ambiente | A localização no mundo onde sua implantação do NiCE CXone está hospedada. Pode ser: Austrália (AU1), Canadá (CA1), Europa (EU1), Japão (JP1), América do Norte (NA1) ou Reino Unido (UK1). O desenvolvedor deve usar a mesma região onde seu sistema NiCE CXone está hospedado, caso contrário a conexão de chat será rejeitada. |
| Contato, Cliente e Usuário | Esses termos todos se referem ao usuário final do aplicativo móvel. A ajuda online normalmente usa o termo contato. Na documentação do SDK e nos comentários do código, é provável que você veja cliente e usuário. |
| NiCE CXone | A plataforma principal em que você gerencia e acessa todas as ferramentas de experiência do cliente que NiCE CXone oferece. Dependendo de quais recursos de chat você deseja oferecer em seu aplicativo móvel, um administrador com as permissões de conta de usuário necessárias deve concluir várias tarefas de configuração em NiCE CXone. |
| Digital Experience (DX) | A seção de NiCE CXone onde você pode gerenciar tudo sobre digital channels. |
| Marca | Sua empresa ou conta em NiCE CXone, identificada por um brandId numérico. Todas as configurações de chat ficam sob uma marca. |
| Canal Livechat (sessão única) | Uma sessão síncrona, roteada por agente. O chat deve ser iniciado explicitamente (startChat()) e pode ser encerrado (endChat()), e o cliente pode esperar em uma fila DE espera. O SDK retorna um LivechatThread para esses canais. |
| Conversa | Uma conversa dentro de um canal, identificada por um id da conversa. Ela contém o histórico de mensagens e é a sua principal referência para enviar e receber mensagens. |
| Contato, caso e interação |
Uma única interação No NiCE CXone ajuda online, o termo interaction é usado com mais frequência. O termo case é usado em algumas páginas de ajuda de Digital Experience (DX). Contact é usado em contextos técnicos, como SDK ou conteúdo de ajuda de Studio, e geralmente se refere ao id que NiCE CXone atribui a um segmento de uma conversa ou interação completa (contactId). |
| Mensagem | Um único item em um tópico — texto, um anexo ou conteúdo interativo — criado pelo cliente ou pelo agente. |
| Agente | Um ser humano (ou bot) do lado de NiCE CXone que atende o contato. A atribuição e a digitação do Agente aparecem como eventos. |
| Visitante ou visita | Identificadores de análise leves para a pessoa que está navegando (visitorId) e sua sessão de navegação atual (visitId). Eles são gerados para você caso não os forneça e são importantes principalmente para chat proativo e análises. |
Pré-requisitos
-
TypeScript 4.9+ (o SDK fornece suas próprias definições de tipo).
-
Tempo de execução ES2022. O SDK depende de API padrão do navegador: WebSocket, EventSource, crypto, Intl, Promise, EventTarget, CustomEvent, JSON, Date.
-
Um empacotador de módulos (webpack, Vite, Create React App, etc.). O SDK é distribuído como módulos ES e deve ser empacotado em seu aplicativo.
-
Um aplicativo personalizado (você constrói a UI).
Política de Suporte de versão
NiCE oferece suporte somente às duas versões principais mais recentes do SDK da Web de bate-papo (seguindo o versionamento semântico). Versões mais antigas são descontinuadas e listadas como tal em GitHub. Para garantir suporte continuado e acesso aos recursos mais recentes, atualize para a versão mais nova prontamente. As versões do SDK seguem seu próprio ciclo de vida e são publicadas conforme necessário. Elas não estão vinculadas à agenda trimestral de lançamentos padrão do NiCE CXone.
Antes de Iniciar o Desenvolvimento
Considere os itens a seguir antes de criar com o SDK móvel:
- Você tem uma conta de administrador e de agente no NiCE CXone? Um administrador pode ajudá-lo a configurar os recursos necessários na NiCE CXoneplataforma?
- Você tem canais de chat existentes ou quer criar um novo?
- Você deseja oferecer conversas single-thread ou multi-thread?
- Quais tipos de mensagens interativas você deseja configurar? Quais são alguns casos de uso em que você pode aproveitar essas mensagens interativas?
- Você usará ações proativas como pop-ups ou mensagens de boas-vindas?
Inicializar chat corretamente
Seus desenvolvedores devem conectar seu aplicativo a NiCE CXone para iniciar a comunicação em ambas as direções. Isso cria uma conexão WebSocket. Os Desenvolvedores podem fazer isso chamando await sdk.connect(). Certifique-se de instruir seus desenvolvedores a fazer isso somente para conversas de chat ativo. Isso garante que o WebSocket seja executado somente quando necessário.
Instalação
npm install @nice-devone/nice-cxone-chat-web-sdk
Inicialização
Importe a exportação padrão e crie uma instância com sua marca, canal e região. storagee cacheStorage são opções obrigatórias — passe null para desativar a persistência e o cache, ou passe implementações reais para ativá-los (veja abaixo).
Configuração mínima (sem persistência)
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,
});
Configuração de Produção (com Persistência)
import ChatSdk, { CacheStorage, EnvironmentName } from '@nice-devone/nice-cxone-chat-web-sdk';
const sdk = new ChatSdk({
brandId: 1234,
channelId: 'chat_abcd1234-...',
Identificação do cliente: 'your-customer-id',
environment: EnvironmentName.EU1,
storage: window.localStorage,
cacheStorage: new CacheStorage(window.localStorage),
});
Notas sobre Opções obrigatórias
-
brandId and channelId — identificam o canal (crie um canal de chat no CXone para obtê-los).
-
Identificação do cliente — obrigatório, a menos que você use sessões seguras (securedSession); nesse caso, a plataforma estabelece a identidade. Consulte authentication.md.
-
Ambiente — seleciona a região do CXone (ex.: EU1, NA1, AU1). Escolher a região errada significa que o SDK se comunica com o gateway errado.
Conectando
O SDK não se conecta automaticamente. Abra o WebSocket explicitamente:
await sdk.connect();
connect() é resolvido como true quando cria a conexão e false se uma já existir — ele nunca abre um segundo soquete. Chame-o uma vez por ciclo de vida da página; o SDK gerencia a reconexão, o heartbeat e a atualização do token a partir daí.
Importante: Chame connect() Somente para conversas de chat ativo, para que o WebSocket seja executado apenas quando necessário.
Inspecionando informações do Canal
Você pode consultar a configuração do canal e a availability sem abrir uma conexão — útil para decidir se deve mostrar o widget de chat.
const info = await sdk.getChannelInfo();
const { status } = await sdk.getChannelAvailability(); // 'online' | 'offline'
getChannelInfo() retorna um objeto ChannelInfo com:
-
isLiveChat— indica se este é um canal de livechat. -
Configurações — restrições de upload de arquivo (settings.fileRestrictions) e feature flags (settings.features).
-
traduções — cadeias de caracteres localizadas para o idioma configurado.
Ambas as chamadas também estão disponíveis como funções independentes, caso você precise de dados de canal antes de construir uma instância de SDK.
Abrindo uma Conversa e Enviando / Recebendo Mensagens
A Thread é o seu identificador para uma conversa. Obtenha-o com getThread(threadId) — síncrono, sem solicitação de rede. Retorna Thread para canais de mensagens ou LivechatThread para livechat. Chame somente após a resolução 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');
// Escute as mensagens recebidas 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);
},
);
Carregar histórico existente (opcional).
const recovered = await thread.recover();
console.log('Recovered messages:', recovered.messages);
Enviar uma mensagem de texto.
await thread.sendTextMessage('Olá! preciso de ajuda.');
Notas
-
onThreadEvent(type, handler) retorna uma função de cancelamento de registro. Restrinja event.detail com guardas de tipo antes de ler os dados.
-
recover() carrega o estado da thread a partir do servidor. Encapsule em try/catch — ele rejeita com ThreadRecoverFailedError se a thread não existir.
-
Canais de livechat: chame await (thread as LivechatThread).startChat() antes de enviar mensagens.
Exemplo Cheio
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 disponibilidade antes de exibir a UI.
const { status } = await sdk.getChannelAvailability();
if (status === 'offline') {
console.log('No agents available right now.');
}
// 3. Conectar uma vez.
await sdk.connect();
// 4. Abra um thread e escute as mensagens.
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. Envie a primeira mensagem.
await thread.sendTextMessage('Hi there!');
}
startChat();
Próximas etapas
-
configuration.md — ambientes, pontos de extremidade personalizados, informações de canal e todas as opções do SDK.
-
authentication.md — sessões protegidas e identidade do cliente.
-
connection-guidance.md — ciclo de vida da conexão, reconexão e eventos de autenticação.
-
events-and-errors.md — o modelo de evento, os protetores de tipo e os tipos de erro do SDK.
-
messaging-and-rich-content.md — anexos, postbacks, respostas rápidas e mensagens avançadas.
-
threads-and-livechat.md — vários threads vs. livechat, filas, digitação e confirmações de leitura.
-
proactive-and-visitors.md — chat proativo, visitantes e visitas.
-
migration.md — atualizando entre versões do SDK.