Saltar al contenido principal
ChattyBox Logo

SDK de JavaScript

El SDK de JavaScript es la opción recomendada para nuevas integraciones dirigidas por desarrolladores. Crea tu propia experiencia de chat mientras ChattyBox gestiona la recuperación, las citas, las conversaciones y el escalado. Si quieres una interfaz lista para usar sin añadir código a tu aplicación, utiliza en su lugar el widget alojado, que cuenta con soporte completo.

Antes de empezar​

  1. Crea un proyecto e indexa tu contenido.
  2. Prueba preguntas representativas en el panel.
  3. Abre la pestaña Insertar del proyecto.
  4. Crea o selecciona una clave API pública del widget y configura sus orígenes permitidos.
  5. Copia la URL de la API del widget que aparece junto al fragmento de inserción.

Las claves API públicas del widget están diseñadas para aparecer en el código del navegador. Identifican un proyecto, pero no son credenciales de administración. Restringe las claves del navegador a los dominios que deban poder llamar a tu chatbot.

Instalación​

bun add @openstaticfish/chattybox

El paquete es un cliente ESM para aplicaciones actuales de Node.js y de navegador que proporcionen fetch.

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

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

La respuesta contiene:

CampoTipoDescripción
messagestringLa respuesta generada.
conversationIdstringIdentificador utilizado para continuar esta conversación.
sourcesstring[]URL de las fuentes recuperadas para la respuesta.

Continuar una conversación​

Conserva el ID de conversación devuelto en el estado de tu interfaz y envíalo con el siguiente mensaje:

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

No reutilices un mismo ID de conversación para visitantes distintos que no tengan relación entre sí. Para crear una conversación nueva, omite conversationId en su primer mensaje.

Gestionar 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.

Compatibilidad avanzada con el widget​

El SDK también expone getWidgetConfig() y getWidgetTranslations(locale). Estos métodos son útiles para clientes que quieran reproducir la configuración del proyecto y las etiquetas localizadas del widget alojado. Una interfaz totalmente personalizada puede ignorarlos.

Próximos pasos​