SDK de JavaScript

El paquete npm es la forma recomendada de integrar ChattyBox. Importe un cliente en su aplicación, configure su clave pública y la URL de la API, y después monte la interfaz gestionada donde la aplicación la necesite o use los métodos headless con sus propios componentes.

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

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

Llame a mountWidget() en el código del navegador desde el componente o layout donde deba estar disponible la interfaz gestionada. Puede pasar { locale: 'fr' } para una ruta con una configuración regional específica.

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, cree una clave de navegador y restrinja sus orígenes permitidos.
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 de API del widget están diseñadas para aparecer en el código del navegador. Identifican un proyecto, pero no son credenciales de administración. Restrinja las claves de navegador a los dominios a los que se deba permitir llamar al chatbot. El paquete es un cliente ESM para aplicaciones actuales de Node.js y navegador que proporcionan fetch.

Monte el widget alojado desde el código

Use esta opción cuando quiera la interfaz gestionada de ChattyBox y, al mismo tiempo, controlar desde el código de la aplicación dónde se monta:

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

Carga la interfaz gestionada una sola vez y no está disponible durante el renderizado en el servidor.

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	La respuesta generada.
conversationId	string	Identificador utilizado para continuar esta conversación.
sources	string[]	URL de las fuentes recuperadas para la respuesta.

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 mismo ID de conversación entre visitantes sin relación. Cree una conversación nueva omitiendo conversationId en el primer mensaje de cada uno.

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. code está presente cuando la API devuelve un código de error estructurado.

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 completamente personalizada puede ignorarlos. Conserve la conversationId de cada visitante en el navegador o el estado de sesión de ese visitante; nunca comparta un ID de conversación global.

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.