Integra por HTTPS, no por diapositivas
Despliega chat de servidor a servidor, transmite tokens en tiempo real a tu propia interfaz y dispara automatizaciones desde webhooks que terminan en tu host de FlexyAgents. Las rutas que aparecen a continuación son los manejadores reales de Next.js: copia los valores desde Despliegue tras generar la conexión a la API de FlexyAgents.
- POST /api/agents/{agentId}/chat acepta Bearer ligados a la conexión FlexyAgents de automatización y ejecuta la misma pila RAG + modelo que el widget
- El streaming opcional devuelve fragmentos JSON NDJSON; sin streaming la respuesta es un único payload del asistente
- Límites por IP antes de los planes; los planes alojados aplican presupuestos de tokens y BYOK devuelve errores explícitos si falta la clave del proveedor
- Disparadores webhook, callbacks de canal e integraciones salientes comparten el mismo modelo de tenancy—todo se resuelve a organización y agente
¿Necesitas claves antes? Crea un espacio de trabajo y abre Configuración → Claves de API o el modal de conexión del agente.
Superficies HTTP de un vistazo
Las rutas reflejan el árbol de rutas de Next.js. Sustituye los marcadores por el ID del agente y el host de tu pantalla de despliegue.
- POST/api/agents/{agentId}/chat
Chat del agente y streaming
Envía un cuerpo JSON con un array messages (rol + contenido) y el flag stream opcional. Bearer valida contra la clave API de FlexyAgents guardada en la conexión del agente; con clave correcta se resuelve la organización automáticamente.
- POST/api/webhooks/automations/...
Entrada de disparadores de automatización
Las automatizaciones publicadas pueden exponer URLs webhook que deserializan payloads y llaman a executeAutomation—útil cuando tus servicios deben iniciar flujos sin OAuth.
- GET/POST/api/webhooks/*
Webhooks de canales y proveedores
Rutas hermanas bajo /api/webhooks gestionan WhatsApp, Instagram, Facebook Messenger, email entrante y callbacks similares para que el despliegue omnicanal quede en tu dominio.
- —Integraciones → Webhooks
Entrega saliente
Configura webhooks salientes firmados desde el panel cuando quieras que FlexyAgents envíe eventos de conversación o del sistema a tu SIEM, data lake o puente con ticketing.
Llamada mínima sin transmisión en tiempo real
curl -X POST "https://TU_HOST_APP/api/agents/ID_AGENTE/chat" \
-H "Authorization: Bearer TU_CLAVE_API_FLEXYAGENTS" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Hola"}],"stream":false}'Sustitúyelos por los valores copiados de Despliegue → API tras conectar la aplicación de FlexyAgents en ese agente.
Invocar
Chat HTTPS-first con el mismo cerebro que el widget
La pantalla de despliegue copia un curl contra tu host en vivo. El handler valida claves API con el almacén de conexiones de automatización, carga comportamiento + conocimiento e incrementa uso como cualquier otro canal.
Contrato del array messages
El cuerpo debe incluir al menos un turno de chat. El ejecutor recorta el historial al último mensaje de usuario para la recuperación pero acepta arrays multi-turno para uso futuro.
- Roles limitados a user, assistant o system en el validador
- Metadatos solo en cabeceras cuando esté documentado—prioriza el contrato JSON
- Formas inválidas devuelven 400 con detalle Zod para depurar más rápido
Modo streaming
Con stream: true recibes fragmentos NDJSON (un objeto JSON por línea) que el frontend puede volcar en UI a medida que llegan tokens.
- Ideal para clientes móvil o escritorio con paridad con el widget alojado
- Errores a mitad de stream también se serializan como líneas JSON
- Desactiva streaming si los proxies amortiguan agresivamente las respuestas
Claves Bearer API vs cookies de sesión
Las cuentas de servicio deben usar la clave de conexión FlexyAgents generada por agente. Las pruebas interactivas pueden usar sesión del panel, pero servidor a servidor siempre Bearer.
- Las claves se cifran en reposo junto al resto de credenciales de automatización
- Rotar una clave no cambia el ID del agente en tu URL
- Claves inválidas o ausentes devuelven 401 antes de gastar modelo
Límites que verás en producción
Límites con Redis devuelven 429 ante picos. El plan añade MESSAGE_LIMIT_REACHED para cupos mensuales alojados/BYOK y techos de tokens en inferencia alojada.
- Automatizaciones y chat comparten la misma contabilidad a nivel org
- Registra IDs de correlación de los errores al hablar con soporte
- Actualiza o añade créditos donde el billing permita más caudal
Eventos
Trae tu stack a FlexyAgents—y empuja eventos de vuelta
Las rutas entrantes normalizan firmas de vendor mientras la configuración saliente vive junto al resto de integraciones. Las automatizaciones también pueden POST HTTP arbitrario dentro de un flujo.
Disparadores webhook de automatización
Cuando un flujo publica un disparador webhook, FlexyAgents guarda el segmento de ruta y verifica payloads antes de llamar a executeAutomation con el cuerpo parseado.
- Combina con pasos del agente que llamen a Slack, CRMs o REST propios
- El gating por plan puede exigir nivel superior antes del ingreso genérico
- Los logs aparecen en el mismo historial de ejecución que los disparadores OAuth
Callbacks de proveedores de canal
WhatsApp, Instagram DM, Messenger y email entrante registran endpoints HTTPS públicos para que Meta, Twilio o el correo verifiquen y entreguen eventos.
- Configura URLs de callback en la consola del vendor para que coincidan con tu host de despliegue
- Los handshakes de verificación ocurren en las mismas rutas que el tráfico real
- Mantiene payloads sensibles en infraestructura que ya auditas
Acciones HTTP salientes
Las acciones de automatización pueden POST o PUT a URLs del cliente con cuerpos plantillados—p.ej. “notificar Opsgenie” o “crear ticket Jira” sin esperar conector de primera parte.
- Mapea campos del disparador a cuerpos JSON con el builder de automatizaciones
- Reintentos y errores siguen los defaults del ejecutor de automatizaciones
- Combina con pasos del agente para resúmenes legibles antes de entregar
Referencia
Especificaciones, docs y herramientas exploratorias
Las páginas de marketing son narrativas; los ingenieros deben apoyarse en /docs, definiciones OpenAPI en el repo y los snippets de despliegue que siempre coinciden con tus IDs de tenant.
Centro de documentación
Empieza en /docs con guías conceptuales y enlaza a /api para inicios rápidos, primers de autenticación y referencias en pestañas cuando existan.
- Ejemplos con curl, JavaScript y patrones de embed del widget
- Promesas de SDK/Postman deben coincidir con lo que realmente distribuimos
- Reporta lagunas vía soporte para alinear marketing y redacción técnica
OpenAPI como fuente de verdad
El repositorio incluye OpenAPI completo con esquemas de auth, payloads de chat y recursos REST auxiliares—genera clientes o importa a Postman desde ese archivo.
- El versionado sigue el ritmo de releases del paquete, no esta landing
- URLs base de staging y producción están en servers del spec
- En local golpeas el mismo path /api/agents/{id}/chat que en producción en tu host de tenant
Widget y compañeros móviles
No toda experiencia necesita REST crudo—el script embebido llama al mismo endpoint de chat con contexto de visitante. Combina API con widget para autoservicio web y jobs backend.
- Las páginas alojadas reutilizan la configuración del agente que ya probaste
- CSP y cookies deben permitir el origen del widget que configures
- Enlaces profundos desde email pueden abrir chat alojado con query params
Combina las APIs con Automatizaciones, Canales y gobernanza en Estadísticas.
Siguiente paso
Copia un curl que funcione y prepáralo para producción
Genera la clave de conexión de FlexyAgents, pégala en tu almacén de secretos y apunta los webhooks de automatización a las rutas que controlas. Cuando estés listo, conecta la observabilidad al mismo espacio de estadísticas que ya usa tu equipo de éxito de cliente.