Guía de integración para desarrolladores
Resumen para desarrolladores
WebChatAgent ofrece tres formas de poner un chatbot frente a sus usuarios. Elija una según el nivel de control que necesite sobre la interfaz.
| Integración | Lo que obtiene | Ideal para |
|---|---|---|
| Integración mediante Widget | Una UI de chat lista para usar desde una sola etiqueta de script | Sitios web y aplicaciones web |
| REST API | Enviar un mensaje, recibir una respuesta (petición/respuesta) | UIs personalizadas, aplicaciones móviles, scripts de servidor |
| WebSocket API | Flujo de mensajes en tiempo real con indicadores de escritura y presencia | Paneles de Chat en vivo, herramientas de agentes |
| SDK de JavaScript | Paquete de npm con tipos para la REST API y la WebSocket API | UIs de chat personalizadas en JavaScript o TypeScript |
| Webhook | Nuevos leads y citas como solicitud JSON firmada a su servidor | Sincronización con el CRM, automatizaciones |
Las tres opciones se comunican con el mismo chatbot, comparten la misma Base de conocimiento y cuentan para la misma cuota de mensajes. Puede combinarlas, por ejemplo, insertar el Widget en su sitio y crear un Panel de agentes interno sobre la WebSocket API.
Integración mediante Widget (el más rápido)
Añada el chatbot a cualquier Sitio web con una sola etiqueta de script y un elemento HTML personalizado (<web-chat-agent chatbot-id="...">). Sin frameworks, sin paso de compilación. Todos los colores, textos y herramientas se configuran en el Panel y se aplican automáticamente. Esta es la opción adecuada para el 90% de los sitios web.
- Guía de integración mediante Widget: etiqueta de script, elemento personalizado, todos los atributos HTML, CSS personalizado, modo integrado y uso en SPAs
REST API
Cuando necesite su propia interfaz de chat, ya sea una aplicación móvil, un componente web personalizado o una automatización en el backend, llame directamente al endpoint de chat. Envía un message junto con su chatbotId y recibe una reply generada por IA con sus fuentes. Un ID de sesión devuelto en una cabecera de respuesta mantiene la coherencia en conversaciones de varios turnos.
- Referencia de la REST API: endpoints, autenticación de Dominio, campos de petición/respuesta, códigos de error y ejemplos de código en cURL, JavaScript, Python y PHP
SDK de JavaScript
¿Está creando una UI de chat personalizada en JavaScript o TypeScript? El paquete de npm webchatagent envuelve la REST API y la WebSocket API: respuestas en streaming, Carga de archivos, Comentarios, Formularios para captar clientes potenciales y Chat en vivo con su equipo, con tipos completos de TypeScript y sin dependencias.
- SDK de JavaScript: instalación, primer Mensaje, streaming, transferencia a humanos. Paquete en npm, código fuente en GitHub
WebSocket API
Para Chat en vivo, donde los mensajes deben llegar al instante y necesita indicadores de escritura, presencia y Traducción automática. El mismo socket alimenta los widgets para visitantes y el Panel de agentes. Utilícelo para crear una consola de agentes personalizada o para gestionar el Chat en vivo desde su propio backend.
- Referencia de la WebSocket API: Conexión, roles, los eventos que envía y recibe, y un ejemplo de cliente en funcionamiento
¿Cuál debo utilizar?
| Caso de uso | Recomendado |
|---|---|
| Añadir un chatbot a un Sitio web | Integración mediante Widget |
| Renderizar el chat dentro del diseño de su propia página | Chat integrado (integración mediante widget) |
| UI de chat personalizada en JavaScript o TypeScript | SDK de JavaScript |
| UI de chat personalizada o aplicación móvil | REST API |
| Automatización entre servidores (sin UI) | REST API |
| Panel de Chat en vivo en tiempo real para agentes humanos | WebSocket API |
Consulte Casos de uso para ver escenarios concretos que estas integraciones hacen posibles.
