SDK de JavaScript

:::note Estado de versión El SDK npm publicado 0.1.4 valida baseUrl, envuelve cuerpos de respuesta ilegibles y reintenta config HTTP 400 una sola vez. Con widget.js v15, remove()/window.ChattyBox.destroy() permite teardown; sendMessage() headless no reintenta automáticamente. :::

El paquete npm es la forma recomendada de integrar ChattyBox desde código. Carga el widget flotante desde un layout persistente o use los métodos headless para su propia interfaz.

Inicio 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();

// Mantenga este loader durante la vida de la página, incluida la navegación SPA.

Llame mountWidget() después de que exista document.body, nunca durante renderizado ni en servidor. Inserta un widget flotante bajo document.body; { locale: 'fr' } solo solicita el idioma al iniciar si el proyecto permite overrides de script.

Obtenga su configuración pública

1. Cree un proyecto e indexe su contenido.
2. Pruebe preguntas representativas en el dashboard.
3. Abra Public Keys y cree una clave de navegador; la restricción de orígenes es opcional.
4. Abra Embed, seleccione esa clave y copie la URL de la API del widget que aparece junto al fragmento generado.

Las claves públicas identifican un proyecto, pero no son credenciales de administración. La restricción opcional compara esquema, host y puerto; usa Origin o el origen de Referer. Sin origen permitido devuelve 401. No es autenticación y Node no envía esas cabeceras automáticamente.

Monte el widget alojado desde el código

Use esta opción para inicializar la interfaz flotante gestionada desde código:

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() devuelve un handle antes de que el script o la UI estén listos. En el SDK publicado 0.1.4, los montajes idénticos comparten el script y cada handle conserva una referencia: remove() es idempotente y solo el último handle cancela inicialización, reintentos y chat en curso, y después elimina UI, estilos, enlaces de fuentes, script y API global. Una clave, URL de API, scriptUrl, locale u opción debug distinta se rechaza mientras queden handles. Con widget.js v15, window.ChattyBox.destroy() hace el mismo teardown. No hay promesa ready, contenedor ni actualización reactiva del locale; elija un único loader.

Cree su propia interfaz

Use los siguientes métodos headless cuando su aplicación sea responsable de la lista de mensajes, la entrada, los estados de carga y error, las citas y la accesibilidad.

Envíe un mensaje

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);

Establezca PUBLIC_CHATTYBOX_API_URL en la URL exacta de la API del widget que aparece en la pestaña Embed. El SDK acepta tanto la raíz del despliegue como una URL que termine en /chat.

La respuesta contiene:

Campo	Tipo	Descripción
message	string	Respuesta o fallback; renderícela como texto o Markdown saneado, no HTML crudo.
conversationId	string	Identificador utilizado para continuar esta conversación.
sources	string[]	Fuentes, que pueden estar vacías en un fallback; valide HTTP(S) antes de enlazar.

Continúe una conversación

Conserve el ID de conversación devuelto en el estado de la interfaz y envíelo con el siguiente mensaje:

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

No reutilice un ID entre visitantes. Omitir o pasar null inicia una conversación; el ID agrupa mensajes almacenados, pero los turnos anteriores no se pasan al modelo. Haga cada seguimiento autocontenido.

sendMessage() solo acepta message, conversationId e idempotencyKey: no acepta sourceUrl, locale ni opciones de modelo. Valide mensajes no vacíos de hasta 2.000 caracteres. Use una idempotencyKey única por mensaje lógico y reutilice la entrada exacta al reintentar; el SDK no reintenta ni ofrece streaming, timeout o AbortSignal.

Gestione los errores

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 contiene el estado HTTP y code es opcional. Errores de red no se envuelven. No invente un campo de respuesta para distinguir fallback: no existe.

Reutilice la configuración y las traducciones del proyecto

El SDK también expone getWidgetConfig() y getWidgetTranslations(locale). Estos métodos permiten a los clientes reproducir la configuración del proyecto y las etiquetas localizadas del widget alojado:

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

Una interfaz personalizada puede ignorarlos. getWidgetConfig() devuelve localeMode, defaultLocale y allowLocaleOverride cuando están disponibles; respete fixed/auto y los overrides si reproduce el widget. Las etiquetas no determinan el idioma ni la calidad de la respuesta.

Próximos pasos

• ¿Prefiere una interfaz gestionada sin compilación? Instale widget.js.
• Personalice la interfaz alojada en Personalización del widget alojado.
• Antes del lanzamiento, pruebe las restricciones de origen, las respuestas de respaldo, las citas y el comportamiento móvil con la checklist de lanzamiento.