La API Conversation AI de Ropofy brinda a los desarrolladores control programático sobre agentes de IA, acciones y generación de conversaciones. Usa tokens seguros y permisos granulares para automatizar la configuración de agentes, integrar con aplicaciones externas y exportar datos de conversación para análisis o cumplimiento. Esta guía explica qué es la API, sus beneficios, opciones de autenticación (PIT y JWT), familias de endpoints y la configuración paso a paso con capturas de pantalla.

---

¿Qué es la API de Conversation AI?

La API Conversation AI expone las mismas capacidades centrales disponibles en la interfaz UI de Conversation AI (crear y gestionar agentes, adjuntar acciones y obtener detalles de respuestas de IA), de modo que tu equipo pueda automatizar configuraciones y conectar Conversation AI con tus propios sistemas. Usando esta API, puedes aprovisionar agentes a escala, programar actualizaciones de acciones y recuperar datos de generación a nivel de mensaje para informes y auditorías.

---

Beneficios clave de la API Conversation AI

Entender los beneficios prácticos te ayuda a decidir cuándo usar la API frente a la interfaz UI. Estos puntos destacan los resultados que los equipos suelen automatizar: aprovisionamiento más rápido, configuración consistente a escala y acceso confiable a datos detallados de conversación.

Onboarding más rápido: Automatiza la creación de agentes y la asignación de acciones para nuevas ubicaciones o clientes en minutos.
Configuración escalable: Aplica configuraciones y acciones consistentes en muchos subcuentas vía scripts o procesos CI/CD.
Análisis profundo: Recupera generaciones (detalles de respuestas de IA) para alimentar dashboards, flujos de trabajo de QA, auditorías y exportaciones para cumplimiento.
Integración flexible: Orquesta Ropofy con tus herramientas internas: dispara flujos de trabajo, rastrea resultados y registra eventos externamente.
Seguridad de privilegio mínimo: Usa permisos de solo lectura o escritura para limitar el acceso exactamente a lo que tu integración necesita.

---

Autenticación (PIT y JWT)

Elegir el método de autenticación correcto garantiza un acceso seguro y confiable. Los Tokens de Integración Personal (PIT) son rápidos de generar y asignar permisos, mientras que los JSON Web Tokens (JWT) soportan flujos de apps basados en OAuth. Ambos pueden usarse para acceder a la API Conversation AI.

Abre Configuración → Integraciones Privadas en tu subcuenta (ubicación) de Ropofy.

Asígnale información básica (nombre y descripción).

Selecciona los permisos de Conversation AI.

Crea el token y haz una copia del mismo.

Mantén y utiliza el token de manera adecuada.

---

Documentación de la API

Consulta la documentación completa de la API aquí Marketplace API 2.0 Actions de Conversation AI

Acciones

Adjuntar acción a agente
Listar acciones de un agente
Obtener acción por ID
Actualizar acción
Eliminar acción de agente
Actualizar configuraciones de seguimiento

Agentes

Crear un agente
Buscar agentes
Actualizar agente
Obtener agente
Eliminar agente

Generaciones

Obtener detalles de generación

---

Preguntas Frecuentes

P: ¿Necesito un token de Subcuenta o de Agencia para Conversation AI?

R: Usa un token de Subcuenta para que las llamadas actúen en el contexto correcto de la ubicación.

P: ¿Puedo usar tanto PIT como JWT?

R: Sí. Puedes autenticarte con cualquiera de los dos métodos. Elige PIT para integraciones servidor a servidor simples; usa JWT para flujos de apps OAuth.

P: ¿Dónde encuentro el agentId?

R: Crea o busca agentes mediante la API de Agentes, y luego usa el campo id retornado en llamadas posteriores.

P: ¿Cómo audito respuestas de IA de forma programática?

R: Usa el endpoint de Generaciones para recuperar detalles de las respuestas a nivel mensaje y guárdalos en tu sistema de análisis o cumplimiento.

P: ¿Qué causa un error 403 si mi token parece válido?

R: La mayoría de las veces, el token no tiene el permiso requerido o no es un token de Subcuenta para la ubicación objetivo.

API Pública de Conversation AI