SDK JavaScript
:::note Estado da versão
O SDK npm publicado 0.1.4 valida baseUrl, envolve corpos de resposta ilegíveis e tenta novamente pedidos de config com HTTP 400 apenas uma vez; sendMessage() não inclui uiLocale. O SDK e o backend no código-fonte atual suportam este contexto de idioma opcional. Com widget.js v15, remove()/window.ChattyBox.destroy() permitem o teardown; sendMessage() headless não tenta novamente automaticamente.
:::
O pacote npm é a forma recomendada de integrar o ChattyBox a partir do código da aplicação. Configure a chave pública e o URL da API e, em seguida, carregue o widget flutuante mantido pelo ChattyBox a partir de um layout persistente no navegador, ou utilize os métodos headless com os seus próprios componentes.
Requisitos de versão: O SDK publicado no npm é o 0.1.4. Esta versão inclui correções do ciclo de vida e das declarações para NodeNext em modo estrito. A limpeza completa do widget também requer o widget.js atualizado; nas instalações autoalojadas, atualize esse ficheiro separadamente.
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();
// Mantenha este loader durante a vida da página, incluindo navegação SPA.
Chame mountWidget() no navegador depois de existir document.body, não durante a renderização nem no servidor. O widget flutuante é acrescentado sob document.body, não dentro do componente. Pode passar { locale: 'fr' } para pedir francês na inicialização, apenas se o projeto permitir substituições de idioma pelo script.
Os nomes import.meta.env.PUBLIC_* dos exemplos são ilustrativos. Use a convenção de configuração pública da sua framework, como import.meta.env.VITE_* no Vite ou process.env.NEXT_PUBLIC_* no Next.js; em Node.js, leia e valide os valores de process.env.
Obtenha a sua configuração pública
- Crie um projeto e indexe o seu conteúdo.
- Teste perguntas representativas em Testar chatbot.
- Em Instalar → Chaves e domínios, consulte ou crie uma chave pública para o navegador e verifique as definições de origem. As chaves criadas sem restrições funcionam em várias origens; uma chave preparada para um site pode já estar restrita.
- Em Instalar → Instalação no site, introduza um URL de site HTTP(S), selecione uma chave adequada e copie o URL da API do widget apresentado no snippet. O seletor apresenta chaves não expiradas que não têm restrições ou são permitidas para a origem desse URL. Para uma chave restrita, introduza uma origem permitida e consulte as restrições em Gerir chaves e domínios permitidos. Se o formulário não estiver disponível, conclua primeiro o passo de configuração apresentado no dashboard.
As chaves públicas da API do widget destinam-se ao código do navegador. Identificam um projeto, mas não são credenciais de gestão. Para reforço opcional, use Instalar → Chaves e domínios → Editar origens e indique as origens exatas permitidas. As restrições não são autenticação; com uma chave restrita, pedidos sem uma origem permitida recebem 401 Invalid API key. O pacote é um cliente ESM para aplicações atuais de Node.js e navegador que fornecem fetch.
As restrições comparam o esquema, o nome do anfitrião e a porta normalizados, não caminhos nem subdomínios com wildcard. A API utiliza o Origin do pedido ou, na sua ausência, a origem de Referer. Uma origem ausente ou não permitida numa chave restrita devolve 401 Invalid API key, tal como uma chave inválida ou expirada. O fetch de Node.js não envia automaticamente nenhum destes cabeçalhos de navegador. Estas verificações não são autenticação e não impedem um cliente que não seja um navegador de falsificar cabeçalhos.
Construtor e exportações
new Chattybox(options) requer apiKey e baseUrl não vazios. No SDK 0.1.4, baseUrl tem de ser um URL HTTP(S) absoluto, sem credenciais, query string ou fragmento. Pode fornecer uma implementação opcional de fetch; caso contrário, é utilizado o fetch global. Copie o URL HTTP da API do widget a partir do snippet de instalação, não o URL do painel nem um URL de cliente Convex .cloud. O SDK remove barras finais e um eventual sufixo /chat; expõe apiKey e o baseUrl normalizado como propriedades de leitura.
O construtor lança um Error normal se as opções forem inválidas, se apiKey ou baseUrl estiver em falta, não for uma string ou estiver vazio, se o fetch fornecido não for uma função ou se o URL não cumprir os requisitos acima. O pacote exporta Chattybox, ChattyboxError e os tipos ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions e HostedWidgetHandle. Não inclui componentes ou hooks React. O bundle IIFE ./browser disponibiliza os dois construtores em window.ChattyboxSDK; carregá-lo não monta, por si só, uma interface.
Monte o widget hospedado a partir do código
Use esta opção quando quiser inicializar a interface flutuante mantida pelo ChattyBox a partir do código da aplicação:
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({ locale: 'fr', debug: false });
mountWidget() devolve um handle antes de o script ou a UI estarem prontos. No SDK publicado 0.1.4, montagens idênticas partilham o script e cada handle mantém uma referência: remove() é idempotente e só o último handle sinaliza a remoção. Com widget.js v15, isto cancela a inicialização, as tentativas e o chat em curso e remove a UI, os estilos, as ligações de fontes, o script e a API global; window.ChattyBox.destroy() faz o mesmo teardown. Uma chave, URL da API, scriptUrl, locale ou opção de debug diferente é recusada enquanto existirem handles. O SDK não disponibiliza uma API própria para atualizar o locale de forma reativa; o loader no código-fonte atual observa alterações diretas a data-locale. Confirme a versão implementada antes de depender desse comportamento.
A limpeza não anula pedidos já processados pelo servidor. O SDK não deteta loaders manuais sem marcação: escolha uma única integração por página e não combine a montagem pelo SDK com um plugin, etiqueta GTM ou outro script. Um fetch personalizado do construtor aplica-se apenas aos métodos headless, não ao widget alojado. Não existe uma promessa de prontidão nem uma opção para escolher um contentor de montagem.
Mantenha o loader numa estrutura persistente durante a navegação normal do lado do cliente. Com o SDK 0.1.4 e o widget.js v15 alojado, use remove() para limpar componentes ou revogar o consentimento. options.scriptUrl tem como valor predefinido https://chattybox.ai/widget.js; altere-o apenas para um loader de pré-visualização de confiança ou autoalojado. options.locale define data-locale quando não está vazio, se o projeto permitir allowLocaleOverride. options.debug define data-debug="true" apenas quando é verdadeiro. handle.element é o elemento HTMLScriptElement injetado ou reutilizado.
O loader alojado v15 repete falhas de transporte, corpos de respostas bem-sucedidas interrompidos, respostas em curso, limites de frequência e erros do servidor com o mesmo corpo e a mesma chave de idempotência. Faz, no máximo, 10 tentativas e nunca agenda uma tentativa automática para além de 30 segundos; atrasos legíveis de Retry-After contam para esse intervalo. Depois de esgotadas as tentativas, Repetir mensagem reutiliza o mesmo pedido lógico; uma nova pergunta inicia outro pedido. JSON inválido ou uma estrutura de resposta inválida numa resposta bem-sucedida constitui um erro de protocolo terminal, sem repetição automática. As respostas da API entre origens têm de expor Retry-After através de Access-Control-Expose-Headers.
Crie a sua própria interface
Use os métodos headless abaixo quando a 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 o URL exato da API do widget apresentado no snippet de Instalação no site. O SDK aceita a raiz da implementação ou um URL terminado em /chat.
A resposta contém:
| Campo | Tipo | Descrição |
|---|---|---|
message | string | A resposta ou a mensagem de fallback configurada. Apresente-a como texto ou Markdown sanitizado, não como HTML bruto. |
conversationId | string | Identificador usado para continuar esta conversa. |
sources | string[] | URLs das fontes da resposta; pode estar vazio numa resposta alternativa. Valide os URLs HTTP(S) antes de apresentar ligações. |
providerError | string (opcional, código-fonte atual) | Código estruturado de falha do fornecedor. Está ausente nas respostas normais e nos fallbacks configurados; trate códigos desconhecidos como uma falha genérica. |
productFallback | 'no_context_ui' | 'no_context_question' (opcional, código-fonte atual) | Identifica uma resposta sem contexto do produto e indica como foi escolhido o idioma; consulte abaixo. |
O SDK npm publicado 0.1.4 não suporta uiLocale. No código-fonte atual, SendMessageInput aceita também uiLocale?: string: o SDK encaminha o valor fornecido sem o alterar e omite-o se não for indicado ou se for undefined; não deteta automaticamente o idioma. O backend no código-fonte atual valida o valor e normaliza-o para o idioma base suportado. Se estiver malformado ou não for suportado, responde com HTTP 400 Invalid uiLocale. Trata-se de contexto de apresentação, não de um mecanismo de autenticação ou autorização.
Antes de enviar, verifique se a mensagem não está vazia e tem no máximo 2.000 caracteres depois de remover os espaços nas extremidades. O backend impõe este limite, mas as falhas de validação interna surgem atualmente como erros HTTP 500 genéricos.
sendMessage(input) devolve Promise<ChatResponse> e aceita message: string, conversationId: string | null opcional e idempotencyKey: string opcional. O código-fonte atual também aceita uiLocale, mas o SDK publicado 0.1.4 não. O SDK envia a chave pública no corpo JSON; não envia contexto da página (sourceUrl ou sourcePath) nem opções do modelo. O método headless não fornece streaming, novas tentativas automáticas, timeouts, opção AbortSignal, armazenamento ou estado de interface. Uma implementação personalizada de fetch pode definir a política de transporte.
Um sinal reconhecido do idioma da pergunta tem prioridade sobre uiLocale nas mensagens de fallback do produto. Se a deteção não for conclusiva ou se basear apenas na heurística de inglês baseada em caracteres ASCII, uiLocale pode determinar o idioma; se nenhum dos dois estiver disponível, aplicam-se os valores predefinidos do produto. Uma mensagem de fallback escrita pelo projeto é apresentada tal como está, em vez do fallback do produto sem contexto. uiLocale não traduz fallbacks escritos pelo projeto nem altera respostas geradas por IA, e não garante a qualidade nem o idioma das respostas.
A API de chat/widget do código-fonte atual acrescenta productFallback apenas às respostas sem contexto do produto; a disponibilidade depende da versão do backend, não da versão do SDK. no_context_ui significa que o idioma do fallback foi escolhido com base no locale da interface ou no locale predefinido, ou que ficou indeterminado; uma interface personalizada pode voltar a localizá-lo através da entrada atual message.noContext do seu catálogo. no_context_question significa que o classificador existente reconheceu o idioma da pergunta; preserve o texto da mensagem devolvida, pois não há garantia de que o classificador o tenha identificado corretamente. O marcador está ausente em fallbacks personalizados, respostas normais, falhas do fornecedor e respostas legadas. Nunca infira a proveniência a partir do texto da mensagem ou da ausência do marcador e ignore códigos futuros desconhecidos.
O SDK npm publicado 0.1.4 não declara productFallback em ChatResponse, mas mantém este campo no objeto JSON devolvido se o backend o fornecer. Valide e restrinja o valor aos códigos conhecidos antes de o utilizar. Não existe um campo geral wasAnswered nem um campo de estado do fallback; não invente um resultado estruturado que indique uma resposta não suportada.
Ao usar uma idempotencyKey, crie uma chave única por mensagem lógica e repita exatamente os mesmos dados de entrada. Com o backend no código-fonte atual, mantenha também o valor original de uiLocale, incluindo a sua omissão, pois o locale normalizado faz parte da impressão digital de idempotência. Um pedido concluído idêntico pode ser reproduzido sem voltar a ser executado e devolve a resposta exata armazenada, com o marcador original, se existir.
Continue uma conversa
Mantenha o ID de conversa devolvido 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. Ao reutilizar o mesmo conversationId, o modelo recebe até 12 mensagens recentes guardadas, cada uma limitada a 2.000 caracteres. É contexto limitado, não a transcrição completa nem memória permanente; repita detalhes mais antigos quando necessário.
Passar null também inicia uma nova conversa. Uma chave pública, as restrições de origem e o ID de conversa não autenticam visitantes nem protegem conversas privadas.
Segurança das novas tentativas
const input = {
message: 'Where is the API reference?',
idempotencyKey: crypto.randomUUID(),
};
const result = await chattybox.sendMessage(input);
// If the response is lost, retry the same input, including its original conversationId.
O SDK envia idempotencyKey como Idempotency-Key, mas não cria a chave nem repete pedidos automaticamente. Use uma chave única por mensagem lógica, com 1 a 128 caracteres que correspondam a [A-Za-z0-9][A-Za-z0-9._:-]*, e conserve a mesma chave e os mesmos dados de entrada em cada nova tentativa, incluindo o conversationId original e a presença ou ausência de uiLocale. Uma alteração dos dados, um pedido em curso ou uma falha terminal pode devolver 409. Não repita indiscriminadamente todos os erros 409 nem gere uma nova chave após uma falha de transporte ambígua.
Os registos concluídos ou falhados expiram 24 horas após a reserva; os pendentes não são recuperados apenas pela passagem do tempo. Uma nova tentativa após a expiração de um registo terminal pode voltar a executar o pedido. Limite o intervalo de novas tentativas e investigue conflitos persistentes.
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 estado HTTP. Falhas de rede e outros erros não HTTP não são encapsulados pelo SDK.
code só está presente quando a API devolve uma string code; a maioria dos erros atuais da API do widget não a inclui. Respostas não 2xx, uma string error não vazia mesmo com HTTP 200, JSON inválido e JSON que não seja um objeto lançam ChattyboxError. Falhas de rede ou de fetch são propagadas sem alteração. O SDK 0.1.4 também encapsula corpos de resposta ilegíveis em ChattyboxError com RESPONSE_BODY_READ_FAILED. Os objetos JSON bem-sucedidos são convertidos para o tipo declarado sem validação em tempo de execução campo a campo.
Os resultados HTTP comuns incluem 400 para dados malformados ou locales de tradução não suportados, 401 para falhas de chave ou origem, 403 para um widget de projeto desativado (incluindo chat headless), 409 para conflitos de idempotência, 413 para corpos de chat com mais de 65.536 bytes, 429 para limite de frequência e 500 para falhas internas. O SDK não disponibiliza cabeçalhos de resposta no resultado nem no erro. O sendMessage() headless não repete pedidos automaticamente; se a interface o fizer, reutilize a mesma idempotencyKey e os dados de entrada inalterados para cada mensagem lógica.
Reutilize as configurações e traduções do projeto
O SDK também expõe getWidgetConfig() e getWidgetTranslations(locale). Estes métodos permitem que os clientes reproduzam as definições do projeto e os rótulos localizados do widget alojado:
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 partilhe um ID de conversa global.
getWidgetConfig() devolve Promise<WidgetConfig> e autentica com Authorization: Bearer. O SDK 0.1.4 repete exatamente uma vez com a chave codificada na query string apenas após HTTP 400, para intermediários que removem o cabeçalho; não repete outros estados. WidgetConfig é um Record<string, unknown> com propriedades opcionais tipadas para ativação, cores, posição, título e saudação, marca, ícones e definições de idioma (localeMode: 'auto' | 'fixed', defaultLocale: string e allowLocaleOverride: boolean). Valide e restrinja os restantes campos desconhecidos antes de os utilizar. Consulte os campos e valores predefinidos atuais do servidor em Personalização do widget alojado. Um pedido de configuração bem-sucedido também marca o widget como instalado no projeto, mesmo que o cliente personalizado nunca apresente um widget.
Os tipos do SDK no código-fonte atual declaram headerTitleIsDefault?: boolean e welcomeMessageIsDefault?: boolean em WidgetConfig. Cada indicador descreve o texto correspondente: true significa que se trata de um texto predefinido localizado do produto; false significa que é texto personalizado e deve ser preservado. Se o indicador estiver ausente, incluindo em respostas antigas, a proveniência é desconhecida; nunca a infira comparando o texto com um valor predefinido. A disponibilidade depende da versão do backend, não da versão do SDK. O SDK publicado 0.1.4 não declara estes indicadores como booleanos, mas o seu tipo Record<string, unknown> e a resposta JSON inalterada permitem aos consumidores restringir os valores em segurança quando são fornecidos. As respostas bem-sucedidas não são validadas nem sofrem coerção campo a campo.
getWidgetTranslations(locale) devolve Promise<WidgetTranslations> com translations: Record<string, string>, dir: 'ltr' | 'rtl' e o locale: string selecionado pelo servidor. Este endpoint é público e não utiliza a chave da API nem as definições de idioma do projeto. Indique um de en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy ou cs. O SDK codifica o locale no URL, mas não o normaliza: fr-CA e FR devolvem 400, ao contrário da normalização de locales regionais do widget alojado. Uma string vazia seleciona inglês no servidor. Todos os catálogos atuais são LTR e podem ser colocados em cache durante uma hora.
Numa interface personalizada, determine o locale pretendido, respeite allowLocaleOverride e as definições fixas ou automáticas do projeto se pretender reproduzir o comportamento alojado, e preveja alternativas para chaves de tradução em falta. Estas definições controlam os rótulos da interface; um cliente headless do código-fonte atual pode também fornecer uiLocale para as respostas alternativas do produto, como descrito acima. Nenhuma destas opções garante a qualidade ou o idioma das respostas geradas por IA.
Próximas etapas
- Prefere uma interface mantida pelo ChattyBox sem build? Instale
widget.js. - Personalize a interface alojada em Personalização do widget alojado.
- Antes do lançamento, teste as respostas de fallback, as citações e o comportamento em dispositivos móveis com o checklist de lançamento. Se ativar restrições de origem, teste também as origens exatas.