Construí sobre iNTELIGENCIA VIVA
La API pública es el punto de extensión para cualquier cosa que un desarrollador quiera construir sobre un workspace: enrutar conversaciones a un sistema propio, darle a un agente de IA una herramienta que consulte el ERP de un cliente, sincronizar contactos con un CRM, o transmitir eventos en vivo hacia tu propio panel. Es REST, versionada como v1, y todo recurso del modelo de datos del producto es alcanzable a través de ella.
Autenticación
Cada solicitud se autentica con una clave de API emitida desde el panel del workspace, enviada como `Authorization: Bearer sk_live_...`.
Cada clave lleva su propio alcance de permisos configurable — una clave puede limitarse a acceso de solo lectura, a recursos específicos, o recibir acceso completo de lectura y escritura, independiente de cualquier otra clave emitida para el mismo workspace.
Las claves se muestran completas una sola vez, en el momento en que se crean; después de eso, solo su titular puede volver a verlas, y cualquier clave puede revocarse de inmediato desde el panel sin afectar a las demás.
Authorization: Bearer sk_live_...Recursos
Todo recurso del modelo de datos subyacente está disponible a través de la API:
| Workspace | Configuración general, idioma por defecto, canales habilitados. |
| Contact | Alta, búsqueda y consulta de los clientes finales que escriben. |
| Conversation | Listar, crear, cerrar y reasignar conversaciones. |
| Message | Enviar y leer mensajes dentro de una conversación. |
| Department | Gestión de equipos y sus reglas de enrutamiento. |
| Agent | Gestión de usuarios humanos, roles y pertenencia a departamentos. |
| AIAgent | Crear y configurar agentes de IA: instrucciones, base de conocimiento, herramientas invocables. |
| KnowledgeSource | Subir y administrar documentos y URLs para RAG. |
| Channel | Configurar canales y sus credenciales. |
| Webhook | Suscribirse a eventos salientes, firmados con HMAC. |
| APIKey | Emitir y revocar claves. |
Eventos de webhook
Suscribí un `WebhookEndpoint` a cualquiera de estos eventos; cada entrega va firmada con HMAC usando el secreto asociado a ese endpoint, así podés verificar que viene de nosotros antes de confiar en su contenido:
| conversation.created | Se inició una conversación nueva en cualquier canal. |
| conversation.assigned | Una conversación se asignó a un agente humano o departamento. |
| conversation.resolved | Una conversación se cerró, por la IA o por un humano. |
| message.received | Llegó un mensaje entrante nuevo de un contacto. |
| message.sent | Se envió un mensaje a un contacto, por la IA o por un agente. |
| handoff.requested | La confianza de la IA bajó del umbral del workspace y pidió un humano. |
| ai_agent.tool_call | Un agente de IA invocó una de sus herramientas configuradas, incluidas herramientas que registraste vos mismo. |
Las entregas se reintentan ante un fallo y no se garantiza exactamente-una-vez — diseñá tu manejador de webhook para que sea idempotente. La semántica completa de entrega y reintentos está documentada en los Términos de la API para Desarrolladores.
Streaming en tiempo real
Para integraciones que necesiten consumir eventos en vivo en vez de, o además de, los webhooks, cada workspace expone un endpoint de streaming por WebSocket:
wss://api.inteligenciaviva.com/v1/workspaces/{id}/streamLímites de tasa y uso justo
El acceso a la API está sujeto a límites de tasa ligados al plan de tu workspace; una solicitud que excede el límite se señala con HTTP 429 y los encabezados de límite de tasa vigentes, para que puedas implementar un backoff correcto. Los límites exactos y los términos plenamente vinculantes del uso de la API — incluido qué podés y qué no podés hacer con los datos que obtenés — están fijados en los Términos de la API para Desarrolladores, enlazados desde la página Legal.