SDK JavaScript

O pacote npm é a forma recomendada de integrar o ChattyBox. Importe um cliente para sua aplicação, configure a chave pública e a URL da API e monte a interface gerenciada onde sua aplicação precisar dela ou use os métodos headless com seus próprios componentes.

Início rápido

bun add @openstaticfish/chattybox

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget();

// Call this from your component's cleanup lifecycle when appropriate.
// widget.remove();

Chame mountWidget() no código do navegador, a partir do componente ou layout em que a interface gerenciada deve estar disponível. Você pode passar { locale: 'fr' } para uma rota com localidade específica.

Obtenha sua configuração pública

1. Crie um projeto e indexe seu conteúdo.
2. Teste perguntas representativas no dashboard.
3. Abra Public Keys, crie uma chave para o navegador e restrinja suas origens permitidas.
4. Abra Embed, selecione essa chave e copie a URL da API do widget exibida junto com o snippet gerado.

As chaves públicas da API do widget foram projetadas para aparecer no código do navegador. Elas identificam um projeto, mas não são credenciais de gerenciamento. Restrinja as chaves do navegador aos domínios que devem poder chamar seu chatbot. O pacote é um cliente ESM para aplicações atuais de Node.js e navegador que fornecem fetch.

Monte o widget hospedado a partir do código

Use esta opção quando quiser a interface gerenciada do ChattyBox, mas controlar a partir do código da aplicação onde ela será montada:

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget();

// Optional cleanup for a component lifecycle:
widget.remove();

A interface gerenciada é carregada uma vez e não fica disponível durante a renderização no servidor.

Crie sua própria interface

Use os métodos headless abaixo quando sua aplicação for responsável pela lista de mensagens, entrada, estados de carregamento e erro, citações e acessibilidade.

Envie uma mensagem

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const answer = await chattybox.sendMessage({
  message: 'How do I get started?',
});

console.log(answer.message);
console.log(answer.sources);

Defina PUBLIC_CHATTYBOX_API_URL como a URL exata da API do widget exibida na aba Embed. O SDK aceita a raiz da implantação ou uma URL terminada em /chat.

A resposta contém:

Campo	Tipo	Descrição
message	string	A resposta gerada.
conversationId	string	Identificador usado para continuar esta conversa.
sources	string[]	URLs das fontes recuperadas para a resposta.

Continue uma conversa

Mantenha o ID de conversa retornado no estado da interface e envie-o com a próxima mensagem:

const followUp = await chattybox.sendMessage({
  message: 'Can you explain the second step?',
  conversationId: answer.conversationId,
});

Não reutilize um ID de conversa entre visitantes sem relação. Crie uma nova conversa omitindo conversationId na primeira mensagem de cada visitante.

Trate erros

import { Chattybox, ChattyboxError } from '@openstaticfish/chattybox';

try {
  await chattybox.sendMessage({ message: 'Where is the API reference?' });
} catch (error) {
  if (error instanceof ChattyboxError) {
    console.error(error.status, error.code, error.message);
  }
}

ChattyboxError.status contém o status HTTP. code está presente quando a API retorna um código de erro estruturado.

Reutilize as configurações e traduções do projeto

O SDK também expõe getWidgetConfig() e getWidgetTranslations(locale). Esses métodos permitem que os clientes reproduzam as configurações do projeto e os rótulos localizados do widget hospedado:

const [config, labels] = await Promise.all([
  chattybox.getWidgetConfig(),
  chattybox.getWidgetTranslations('en'),
]);

Uma interface totalmente personalizada pode ignorá-los. Mantenha a conversationId de cada visitante no navegador ou no estado de sessão desse visitante; nunca compartilhe um ID de conversa global.

Próximas etapas

• Prefere uma interface gerenciada sem build? Instale widget.js.
• Personalize a interface hospedada em Personalização do widget hospedado.
• Antes do lançamento, teste as restrições de origem, as respostas de fallback, as citações e o comportamento em dispositivos móveis com o checklist de lançamento.