Saltar al contenido principal

:::note Versiones independientes El SDK npm publicado es 0.1.4. El código fuente actual del loader alojado es widget.js v16; la versión desplegada puede ser distinta y debe verificarse. Los comportamientos v15 mencionados a continuación corresponden a la versión del loader alojado documentada históricamente. :::

Integre con un asistente de programación con IA

La integración recomendada desde el código de la aplicación es el paquete npm @openstaticfish/chattybox. Permite configurar la clave pública y la URL de la API, cargar la interfaz flotante gestionada de ChattyBox desde un layout persistente del navegador o usar el cliente headless para una interfaz totalmente personalizada.

El script independiente widget.js se documenta al final como alternativa sin compilación para sitios que no pueden instalar paquetes npm.

Antes de empezar​

Complete la configuración del chatbot antes de pedirle a un asistente que edite su aplicación:

  • Verifique respuestas y citas representativas en Probar chatbot.
  • En Instalar → Claves y dominios, revise o cree una clave pública de navegador y compruebe sus restricciones de origen. Una clave preparada para un sitio puede estar ya restringida a ese origen; las claves sin restricciones funcionan desde cualquier origen. Las restricciones son un refuerzo opcional, no autentican a los visitantes.
  • En Instalar → Instalación en el sitio web, seleccione una clave adecuada y copie el fragmento. Use su data-api-url si está presente; de lo contrario, obtenga el endpoint HTTP correcto de la API del widget de la configuración de despliegue antes de integrar.
  • Decida si un widget flotante persistente encaja en la aplicación o si necesita una interfaz personalizada con ubicación y desmontaje específicos para cada ruta.

La clave pública del widget y la URL de la API están destinadas al navegador, pero aun así debe evitar hacer commit de valores específicos del entorno. Nunca proporcione un token de despliegue de configuración (es privado), una credencial de administrador ni un archivo de entorno que no esté relacionado.

Recomendado: monte la interfaz gestionada desde npm​

Este es el prompt predeterminado para React, Next.js, Vite y otras aplicaciones de navegador basadas en paquetes.

Instrucción
Integre el paquete npm de ChattyBox

Integra ChattyBox en esta aplicación usando el paquete npm @openstaticfish/chattybox.

Configuración pública del navegador:
- Clave de API: [PASTE PUBLIC WIDGET KEY]
- URL de la API: [PASTE WIDGET API URL]

Inspecciona primero el framework, el modelo de enrutamiento, el gestor de paquetes, las convenciones de variables de entorno y el layout persistente de la aplicación. Dime qué archivos planeas cambiar antes de editar. Pregúntame si no están claras las rutas en las que debe aparecer ChattyBox.

Requisitos:
1. Instala @openstaticfish/chattybox con el gestor de paquetes que ya utiliza este repositorio.
2. Guarda la clave pública de API y la URL de la API usando la convención del framework para las variables de entorno expuestas al navegador. Añade nombres de marcador de posición a un archivo de entorno de ejemplo, pero no hagas commit de valores reales.
3. Importa Chattybox desde @openstaticfish/chattybox y crea un cliente con apiKey y baseUrl.
4. Llama a client.mountWidget() únicamente desde código del navegador, cuando document.body ya exista, y desde una shell persistente de la aplicación. Carga un widget flotante bajo document.body, no dentro del componente.
5. Conserva el loader durante la navegación SPA permitida. El SDK publicado `0.1.4` cuenta referencias solo para opciones de montaje idénticas; llama a `remove()` para cada handle devuelto cuando el teardown sea intencional. Con el loader alojado v15 documentado, el último handle elimina la interfaz y los estilos que administra, y cancela la inicialización pendiente, los reintentos y el chat en curso; `window.ChattyBox.destroy()` es el equivalente del loader alojado. Comprueba los cambios de ruta y de consentimiento: no cargues el widget antes del consentimiento requerido ni en rutas sensibles o privadas; desmóntalo al excluir una ruta o retirar el consentimiento. Verifica que el loader desplegado admita teardown: ocultar la interfaz o eliminar solo el elemento script no basta. La limpieza no puede deshacer una solicitud que el servidor ya haya procesado.
6. No inyectes widget.js manualmente, no crees un proxy de backend ni introduzcas un segundo loader. mountWidget rechaza una clave, URL de API, URL de script, locale u opción debug diferentes hasta que se hayan eliminado todos los handles existentes; nunca conserva silenciosamente las opciones antiguas.
7. Conserva la navegación, los límites de renderizado, la localización, Analytics, el consentimiento y los estilos existentes. La opción de locale del SDK respeta la política del proyecto sobre overrides de script; el SDK `0.1.4` no ofrece una API reactiva para actualizar el locale ni una promesa `ready`. El código fuente actual del widget alojado v16 puede actualizar las etiquetas del producto cuando cambia el locale resuelto, sujeto a la política de locale del proyecto; verifica la versión del loader desplegado antes de depender de este comportamiento, ya que tiene una versión independiente. El loader alojado v15 documentado programa como máximo 10 intentos de chat dentro de una ventana de reintentos de 30 segundos; no es un plazo máximo estricto para una solicitud en curso. El `sendMessage()` headless no reintenta automáticamente. El SDK `0.1.4` valida `baseUrl` y envuelve los errores de lectura del cuerpo de la respuesta.
8. Haz el cambio más pequeño y específico posible y no lo despliegues.
9. Ejecuta el build, el lint, la comprobación de tipos y las pruebas relevantes del repositorio.
10. Informa de los archivos modificados, las variables de entorno que debo configurar, dónde se monta la interfaz y cómo probarla en el sitio desplegado.

El siguiente código ilustra una función callback del ciclo de vida del navegador; no es una llamada de nivel superior compatible con el renderizado del servidor. Invócala únicamente cuando exista document.body y conserva el handle para desmontajes intencionales:

import { Chattybox } from '@openstaticfish/chattybox';

const client = new Chattybox({
  apiKey: PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: PUBLIC_CHATTYBOX_API_URL,
});

function mountInBrowser() {
  return client.mountWidget();
}

// Conserva el handle durante la navegación permitida y para desmontajes intencionales.

Cree una interfaz personalizada​

Elija esta opción cuando su aplicación deba controlar la lista de mensajes, la entrada, los estados de carga, los errores, las citas y la ubicación, en lugar de montar la interfaz gestionada.

Instrucción
Cree una interfaz headless de ChattyBox

Crea una interfaz de chatbot personalizada usando el paquete npm @openstaticfish/chattybox y su cliente headless.

Configuración pública del navegador:
- Clave de API: [PASTE PUBLIC WIDGET KEY]
- URL de la API: [PASTE WIDGET API URL]

Inspecciona primero el framework de la aplicación, el sistema de componentes, los patrones de estado, los estilos, las convenciones de accesibilidad y la configuración de pruebas. Propón los límites de los componentes y los archivos antes de editar.

Requisitos:
1. Instala @openstaticfish/chattybox con el gestor de paquetes existente del repositorio.
2. Configura un cliente Chattybox con apiKey y baseUrl usando variables de entorno expuestas al navegador; no hagas commit de valores reales.
3. Usa sendMessage() y conserva conversationId en un estado específico del visitante o de su sesión para agrupar mensajes; restablécelo cuando cambie el usuario o la sesión. Nunca lo compartas entre visitantes no relacionados. El modelo recibe hasta 12 mensajes recientes guardados, cada uno recortado a 2.000 caracteres, no la transcripción completa ni una memoria permanente. Una clave pública, las restricciones de origen y los ID de conversación no autentican a los visitantes ni protegen conversaciones privadas. Evita la información sensible: los mensajes pueden guardarse y ser visibles para los propietarios del proyecto. Borrar el estado local no elimina los registros del servidor.
4. Renderiza las respuestas de forma segura como texto o Markdown saneado, y las fuentes HTTP(S) como enlaces accesibles, conservando su orden. Nunca insertes HTML sin procesar que no sea de confianza ni enlaces con esquemas inseguros.
5. Implementa los estados pendiente, vacío, error y reintento. Las respuestas fallback pueden no tener fuentes; no existe un campo general wasAnswered. Cuando el backend proporcione providerError, trata ese campo como opcional y acota de forma segura su tipo antes de usarlo; muestra un error genérico del proveedor en lugar de una respuesta normal y no reintentes a ciegas una respuesta completada con clave de idempotencia. Es posible que el SDK publicado `0.1.4` no incluya tipos para campos de respuesta de la fuente actual; contempla que no estén presentes. Gestiona tanto `ChattyboxError` como los errores de red no envueltos; code es opcional.
6. Rechaza mensajes vacíos o que superen los 2.000 caracteres después de quitar los espacios iniciales y finales, evita los envíos duplicados y garantiza una experiencia accesible con teclado y lector de pantalla. El sendMessage() headless no reintenta automáticamente: usa una idempotencyKey única para cada mensaje lógico y reutiliza exactamente la misma entrada en los reintentos; no reintentes a ciegas todos los 409. El SDK `0.1.4` solo reintenta getWidgetConfig() una vez tras un HTTP 400; el loader alojado v15 documentado reintenta por separado las solicitudes GET de inicio.
7. Monta la interfaz solo en las rutas o el layout que especifique.
8. Sigue los componentes y estilos existentes en lugar de añadir un sistema de diseño nuevo.
9. No cargues widget.js ni llames a mountWidget().
10. Ejecuta el build, el lint, la comprobación de tipos y las pruebas relevantes; después informa de los archivos modificados y de un plan de verificación.

Notas sobre frameworks​

Proporcione al asistente una frase adicional cuando sea necesario:

  • Next.js App Router: «Usa un Client Component pequeño en un layout persistente y llama a mountWidget() desde un efecto exclusivo del navegador, no durante el renderizado».
  • React SPA: «Monta desde la shell persistente. Si el componente posee el último handle del SDK 0.1.4, devuelve remove() para un teardown intencional; de lo contrario, conserva el loader compartido durante los cambios de ruta permitidos».
  • Docusaurus: «Inicializa desde src/theme/Root en el navegador y conserva el loader durante la navegación permitida por la documentación. Verifica la versión desplegada del loader alojado y su comportamiento de locale antes de confiar en las actualizaciones de idioma del lado del cliente; los cambios en la configuración del dashboard siguen requiriendo una reinicialización».
  • Vue, Nuxt, Svelte u otro framework: «Usa el ciclo de montaje exclusivo del cliente en un layout persistente; elige una interfaz headless si necesitas un desmontaje correspondiente».

Revise una integración existente del SDK​

Instrucción
Revise mi integración del SDK de ChattyBox

Revisa esta integración de ChattyBox sin desplegarla ni cambiar código que no esté relacionado.

Comprueba que:
1. @openstaticfish/chattybox esté instalado e importado en lugar de duplicar su comportamiento.
2. Un único cliente Chattybox reciba la clave pública de API y la URL de la API previstas.
3. Las variables de entorno del navegador sigan las reglas de nombres de variables públicas de este framework sin exponer credenciales privadas.
4. El widget alojado use una shell persistente y utilice remove() solo para un teardown intencional de la UI, la exclusión de rutas tras navegar en SPA o la retirada del consentimiento. La interfaz personalizada debe tener una limpieza real del componente.
5. La navegación del lado del cliente y los nuevos montajes durante el desarrollo no creen instancias duplicadas.
6. Los límites de renderizado, la localización, Analytics, el consentimiento, la accesibilidad y el layout existentes permanezcan intactos. Las restricciones de origen son opcionales y no autentican a los visitantes; las claves restringidas requieren un origen de solicitud permitido, y fetch de Node no envía automáticamente las cabeceras del navegador. Confirma que las rutas privadas y la retirada del consentimiento desmonten realmente un widget inicializado, en lugar de limitarse a ocultarlo.
7. La implementación tenga pruebas adecuadas y no incluya una refactorización ajena.

Devuelve los hallazgos por gravedad con rutas de archivo y referencias de línea. Propón solo las correcciones seguras más pequeñas y proporciona los comandos exactos de verificación.

¿No usa npm ni un paso de compilación?​

Use la guía de instalación de widget.js solo cuando el sitio no pueda utilizar el paquete npm, por ejemplo, en HTML sencillo, un campo de código personalizado de un CMS o Google Tag Manager.

Instrucción
Instale el script del widget de respaldo

Instala el widget alojado de ChattyBox en este sitio usando el script exacto generado en mi vista Instalación en el sitio web de ChattyBox:

[PASTE COMPLETE WIDGET SCRIPT]

Inspecciona primero el sitio e identifica el punto de inserción más seguro para las páginas públicas. Carga el script sin cambios exactamente una vez y solo cuando exista el consentimiento requerido; excluye las rutas privadas, de administración y de pago. En los cambios de ruta SPA o al retirar el consentimiento, desmonta intencionalmente cualquier widget inicializado antes de entrar en un estado excluido y vuelve a inicializarlo solo cuando esté permitido. Verifica que el loader desplegado admita teardown: ocultar la interfaz o eliminar únicamente la etiqueta script no basta, y el teardown no puede deshacer solicitudes ya procesadas. Conserva el comportamiento de CSP, no expongas credenciales privadas, no despliegues el cambio e informa de la ubicación modificada y de un plan de pruebas en el navegador.

Pruebe el resultado​

  1. Revise el diff y confirme que no se hayan incluido credenciales reales en un commit.
  2. Ejecute el build, el lint, la comprobación de tipos y las pruebas normales del proyecto.
  3. Despliegue mediante el proceso normal de revisión.
  4. Verifique las rutas previstas en una ventana privada del navegador, incluida la navegación del lado del cliente.
  5. Haga una pregunta compatible, siga una cita y pruebe el comportamiento de respaldo.
  6. Compruebe el diseño móvil, el uso del teclado y la consola del navegador.

Continúe con la referencia del SDK y la checklist de lanzamiento.