Saltar al contenido principal

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; no incluye uiLocale en sendMessage(). El SDK y el backend en el código fuente actual sí admiten este contexto de idioma opcional. 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. Configure la clave pública y la URL de la API; cargue el widget flotante desde un layout persistente o use los métodos headless para su propia interfaz. La limpieza completa del widget también requiere el widget.js actualizado; si lo aloja usted mismo, actualice ese archivo por separado.

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' } establece el valor inicial de data-locale si el proyecto permite overrides de script. El loader del código fuente actual puede reaccionar a cambios posteriores de ese atributo; compruebe el comportamiento del loader desplegado antes de depender de ello.

Los nombres import.meta.env.PUBLIC_* son ejemplos. Use la convención pública de su framework, como import.meta.env.VITE_* en Vite o process.env.NEXT_PUBLIC_* en Next.js. En Node.js, lea y valide los valores de process.env.

Obtenga su configuración pública​

  1. Cree un proyecto e indexe su contenido.
  2. Pruebe preguntas representativas en Probar chatbot.
  3. En Instalar → Claves y dominios, revise o cree una clave pública y compruebe sus orígenes. Las claves sin restricciones funcionan en varios orígenes; una clave preparada para un sitio puede estar ya restringida. Use Editar orígenes para gestionar las restricciones opcionales.
  4. En Instalar → Instalación en el sitio web, introduzca una URL de sitio web HTTP(S), seleccione una clave adecuada y copie la URL de la API del widget del fragmento generado. El selector solo muestra claves no caducadas que no tienen restricciones o están permitidas para el origen de esa URL. Para seleccionar una clave restringida, introduzca un origen permitido; use Gestionar claves y dominios permitidos para consultar sus restricciones. Si el formulario no está disponible, complete primero el paso de configuración indicado en el dashboard.

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.

El SDK 0.1.4 requiere una baseUrl HTTP(S) absoluta sin credenciales, cadena de consulta ni fragmento. Copie la URL de la API del widget, no la del dashboard ni una URL Convex .cloud. En una clave restringida, un origen ausente o no permitido devuelve HTTP 401 Invalid API key. La coincidencia no admite rutas ni subdominios comodín. La comprobación de origen no es autenticación y no impide que un cliente no navegador falsifique las cabeceras.

Constructor y exportaciones​

new Chattybox(options) requiere apiKey y baseUrl como cadenas no vacías y acepta una implementación opcional compatible con fetch; de lo contrario usa el fetch global. El paquete es un cliente ESM para navegadores y versiones actuales de Node.js que proporcionen fetch. El constructor lanza un Error ordinario si faltan las opciones, son inválidas o el fetch proporcionado no es una función. El cliente elimina las barras finales de baseUrl y, después, un sufijo /chat, y expone apiKey y baseUrl normalizada como propiedades de solo lectura.

El paquete exporta Chattybox, ChattyboxError y los tipos ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions y HostedWidgetHandle. No incluye componentes ni hooks de React. El bundle IIFE ./browser expone los dos constructores en window.ChattyboxSDK; cargarlo no monta la interfaz por sí solo.

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: llame a remove() en cada uno. El último handle señala el desmontaje y elimina el script; con el widget alojado widget.js v15, la señal también cancela la inicialización, los reintentos y el chat en curso, y elimina la UI y sus recursos. La limpieza no deshace una solicitud ya procesada por el servidor. Una clave, URL de API, scriptUrl, locale u opción debug distinta se rechaza mientras queden handles. Con widget.js v15, window.ChattyBox.destroy() también desmonta el widget. El SDK no ofrece una API reactiva propia para actualizar el locale; el loader del código fuente actual puede reaccionar a cambios de data-locale, pero debe comprobarse el comportamiento de la versión desplegada. Elija un único loader.

El handle se devuelve de forma síncrona y su campo element contiene el elemento de script insertado o reutilizado. scriptUrl permite elegir un loader confiable de vista previa o alojado por usted; locale solo se aplica si el proyecto permite esa anulación y debug activa los diagnósticos cuando es verdadero. El SDK no detecta loaders manuales sin el atributo marcador: no combine el montaje del SDK con un plugin, una etiqueta GTM ni otro script. El fetch personalizado del constructor solo se usa para los métodos headless, no para el widget alojado. El SDK no ofrece una promesa de disponibilidad ni un destino de contenedor.

El loader alojado v15 reintenta errores de transporte, cuerpos interrumpidos de respuestas correctas, respuestas en curso, límites de frecuencia y errores del servidor con el mismo cuerpo y clave de idempotencia. Realiza hasta 10 intentos en total y no programa reintentos automáticos después de 30 segundos; los retrasos legibles de Retry-After cuentan dentro de ese plazo, que no es un timeout estricto para una solicitud en curso. Tras agotarlos, Volver a intentar enviar el mensaje reutiliza la solicitud lógica y una pregunta nueva inicia otra. JSON o estructura inválidos en una respuesta correcta son errores de protocolo terminales. Para leer Retry-After entre orígenes, la API debe exponer esa cabecera mediante Access-Control-Expose-Headers. Compruebe la versión desplegada del 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 Instalar → Instalación en el sitio web. El SDK acepta tanto la raíz del despliegue como una URL que termine en /chat.

La respuesta contiene:

CampoTipoDescripción
messagestringRespuesta o mensaje fallback configurado; renderícela como texto o Markdown saneado, no HTML crudo.
conversationIdstringIdentificador utilizado para continuar esta conversación.
sourcesstring[]Fuentes, que pueden estar vacías en un fallback; valide HTTP(S) antes de enlazar.
providerErrorstring (opcional, código fuente actual)Código estructurado de error del proveedor. No aparece en respuestas normales ni en fallbacks configurados; trate los códigos desconocidos como un error genérico.
productFallback'no_context_ui' | 'no_context_question' (opcional, código fuente actual)Identifica una respuesta sin contexto propia del producto e indica cómo se eligió el idioma; consulte más abajo.

El SDK npm publicado 0.1.4 no admite uiLocale. En el código fuente actual, SendMessageInput sí acepta uiLocale?: string: el SDK reenvía el valor proporcionado sin modificarlo y lo omite si no se proporciona o es undefined; no detecta el idioma automáticamente. El backend en el código fuente actual valida el valor y lo normaliza al idioma base compatible. Si está mal formado o no es compatible, responde con HTTP 400 Invalid uiLocale. Es contexto de presentación, no un control de autenticación o autorización.

sendMessage(input) devuelve Promise<ChatResponse> y acepta message, conversationId opcional y idempotencyKey opcional; la clave pública se envía en el cuerpo JSON. No envía contexto de página (sourceUrl o sourcePath) ni opciones de modelo. El backend también aplica el límite de 2.000 caracteres, pero sus errores internos de validación se muestran actualmente como HTTP 500 genérico.

Una señal reconocida del idioma de la pregunta tiene prioridad sobre uiLocale para los mensajes fallback propios del producto. Si la detección no es concluyente o se basa únicamente en la heurística de inglés basada en caracteres ASCII, uiLocale puede determinar el idioma; si no se dispone de ninguno de los dos, se aplican los valores predeterminados del producto. Un fallback redactado por el proyecto se muestra tal cual, en lugar del fallback del producto sin contexto. uiLocale no traduce los fallbacks redactados por el proyecto ni modifica las respuestas generadas por IA.

La API de chat/widget del código fuente actual solo añade productFallback a las respuestas sin contexto propias del producto; su disponibilidad depende de la versión del backend, no de la del SDK. no_context_ui indica que el idioma del fallback se eligió mediante el locale de la interfaz o el valor predeterminado, o que quedó indeterminado; una interfaz personalizada puede volver a localizarlo con la entrada actual message.noContext de su catálogo. no_context_question indica que el clasificador existente reconoció el idioma de la pregunta; conserva el texto devuelto, ya que no se garantiza que la clasificación sea correcta. El marcador no aparece en fallbacks personalizados, respuestas normales, errores del proveedor ni respuestas heredadas. Nunca infieras la procedencia a partir del texto del mensaje ni de la ausencia del marcador, e ignora los códigos futuros desconocidos.

El SDK npm publicado 0.1.4 no declara productFallback en ChatResponse, pero conserva este campo en el objeto JSON devuelto si el backend lo incluye. Comprueba el valor de forma segura antes de usarlo. No hay un campo general wasAnswered ni un campo de estado del fallback; no inventes un resultado estructurado que indique una respuesta no compatible.

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 conversationId o pasar null inicia una conversación; el ID agrupa mensajes almacenados. Al reutilizar el mismo conversationId, el modelo recibe hasta 12 mensajes recientes guardados, cada uno recortado a 2.000 caracteres. Es contexto limitado, no la transcripción completa ni memoria permanente; repita los detalles anteriores cuando sea necesario.

sendMessage() no acepta sourceUrl ni opciones de modelo. Valide mensajes no vacíos de hasta 2.000 caracteres tras quitar espacios. Use una idempotencyKey única por mensaje lógico y reutilice la entrada exacta al reintentar; con el backend en el código fuente actual, conserve también el valor original de uiLocale, incluida su omisión, porque el locale normalizado forma parte de la huella de idempotencia. Una solicitud completada idéntica puede reproducirse sin volver a ejecutarse y devuelve la respuesta exacta almacenada con su marcador original, si lo había. El método headless sendMessage() no reintenta automáticamente ni ofrece streaming, timeout o AbortSignal; el SDK 0.1.4 reintenta getWidgetConfig() una sola vez tras HTTP 400.

La clave se envía en Idempotency-Key; el SDK no la genera. Está asociada al proyecto y debe tener entre 1 y 128 caracteres que coincidan con [A-Za-z0-9][A-Za-z0-9._:-]*. Una entrada modificada, una solicitud en curso o un fallo terminal pueden producir HTTP 409. No reintente todos los 409 a ciegas ni genere una clave nueva tras un fallo de transporte ambiguo. Un fetch personalizado puede proporcionar una política de transporte; el método no gestiona almacenamiento ni estado de interfaz.

Los registros de idempotencia completados o fallidos caducan 24 horas después de reservarse; un reintento posterior puede volver a ejecutarse. Los registros pendientes no se recuperan solo por el paso del tiempo. Limite el plazo de reintentos e investigue los conflictos persistentes en lugar de suponer una deduplicación ilimitada.

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.

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 solo aparece si la API devuelve un code de tipo cadena; la mayoría de los errores actuales de la API del widget no lo incluyen. Las respuestas no 2xx, un error de cadena no vacía incluso con HTTP 200, el JSON inválido y el JSON que no sea un objeto lanzan ChattyboxError. Los errores de red no se envuelven; el SDK 0.1.4 sí envuelve cuerpos ilegibles con RESPONSE_BODY_READ_FAILED. Los objetos JSON correctos se convierten al tipo declarado sin validar cada campo. No invente un campo de respuesta para distinguir fallback: no existe.

Entre los estados habituales están 400 por entrada inválida o locales de traducción no admitidos, 401 por clave u origen, 403 por widget desactivado (también en chat headless), 409 por conflictos de idempotencia, 413 por cuerpos de chat de más de 65.536 bytes, 429 por límite de frecuencia y 500 por errores internos. El SDK no expone las cabeceras de respuesta en el resultado ni en el error.

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.

getWidgetConfig() devuelve Promise<WidgetConfig> y usa Authorization: Bearer. El SDK 0.1.4 solo reintenta una vez con la clave codificada en la cadena de consulta después de HTTP 400; no reintenta otros estados. WidgetConfig es un Record<string, unknown> con propiedades opcionales tipadas para habilitación, colores, posición, textos, marca, iconos e idioma; compruebe el tipo de los demás campos antes de usarlos. Una solicitud de configuración correcta también marca el proyecto como instalado, incluso si la interfaz personalizada nunca muestra un widget.

getWidgetTranslations(locale) devuelve Promise<WidgetTranslations>, con translations, dir y el locale seleccionado por el servidor. El endpoint es público y no usa la clave ni los ajustes de idioma del proyecto. Admite en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy y cs. El SDK codifica el locale para la URL, pero no lo normaliza: fr-CA y FR producen HTTP 400; una cadena vacía selecciona inglés. Los catálogos actuales usan escritura de izquierda a derecha y pueden guardarse en caché durante una hora. Resuelva el locale en la interfaz personalizada y prevea valores de respaldo para las claves de traducción que falten.

Los tipos del SDK en el código fuente actual declaran headerTitleIsDefault?: boolean y welcomeMessageIsDefault?: boolean en WidgetConfig. Cada indicador describe el texto correspondiente: true significa que es un texto predeterminado localizado del producto; false, que es texto personalizado y debe conservarse. Si el indicador está ausente, incluso en respuestas antiguas, se desconoce la procedencia; nunca la infieras comparando el texto con un valor predeterminado. La disponibilidad depende de la versión del backend, no de la versión del SDK. El SDK publicado 0.1.4 no declara estos indicadores como booleanos, pero su tipo Record<string, unknown> y la respuesta JSON sin modificar permiten a los consumidores estrechar el tipo de forma segura cuando están presentes. Las respuestas exitosas no se validan ni se someten a coerción campo por campo.

Próximos pasos​