Centro de Ayuda ConversaLabs
es
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

Referencia de API (Swagger / OpenAPI)

Abrir en
Ver como Markdown Abrir en ChatGPT Abrir en Claude

Conversa Labs

Última actualización el 21 de oct de 2026

Visión general

ConversaLabs publica una referencia de superficie pública OpenAPI 3.1 para descubrir e integrar los endpoints que pertenecen a ese contrato. Se produce a partir de rutas y fuentes curadas; no promete que toda ruta interna, módulo habilitable o formulario de la instalación se publique automáticamente.

Hay tres formas de ver la misma referencia:

La referencia agrupa Account/AgentBot en /api/v1, Platform en /platform, Widget en /api/v1/widget, rutas public en /public/api, metadatos públicos de descubrimiento/desafío y caminos de webhook que pertenecen al contrato. Lee la seguridad declarada por operación: no existe un token universal.

Requisitos previos

  • La credencial que exige la operación: token de cuenta/AgentBot, clave de Platform App, token público propio del recurso o ninguna credencial, según el contrato.
  • Un navegador moderno. Para probar llamadas, prefiere un token de un entorno de pruebas.

Paso a paso

  1. Abre la referencia en https://app.conversalabs.com.br/swagger (ReDoc) y navega por los grupos de módulos en la barra lateral.
  2. Localiza el endpoint que necesitas (por método y ruta) y lee sus parámetros, cuerpo y respuestas.
  3. Para probar, abre la referencia interactiva en https://app.conversalabs.com.br/swagger/ui.html.
  4. Lee el requisito de seguridad de la operación antes de Authorize e ingresa solo una credencial compatible con esa ruta.
  5. Elige un endpoint, haz clic en Try it out, completa los parámetros y usa Execute solo cuando el entorno de pruebas y la operación lo permitan.
  6. Revisa la respuesta (estado, cuerpo) y reutiliza el ejemplo de solicitud (cURL) en tu integración.

Configuración y opciones

  • Cobertura y autenticación: las rutas nuevas deben incluirse y revisarse en el contrato. Las operaciones pueden usar api_access_token, clave de Platform App, token de recurso o seguridad vacía explícita; nunca copies una credencial entre superficies por suposición.
  • Webhooks entrantes: un camino acepta llamadas solo cuando el recurso que lo configura está activo y validado. La autenticación varía por proveedor/recurso (firma, secreto, token de verificación o desafío), por lo que no es una API REST genérica para probar con un token de cuenta.
  • Metrics: /monitoring/metrics no es una operación de cliente. Está inerte hasta que el operador defina OPERATIONS_METRICS_TOKEN y exige Authorization: Bearer <token> para una recolección autorizada.
  • MCP y operador: MCP usa perfiles, URLs y credenciales Bearer/OAuth propios. La REST del operador tiene una referencia separada y no se sirve en /swagger.
  • Disponibilidad: en instalaciones self-hosted, la documentación la habilita el operador mediante una variable de entorno (ENABLE_API_DOCS). En la ConversaLabs alojada ya está disponible en las direcciones anteriores.

Casos de uso

  • Determinar si una integración pertenece a Account/AgentBot, Platform, Widget o una superficie pública.
  • Consultar los requisitos de una operación antes de probar una llamada en un entorno controlado.
  • Importar la definición OpenAPI en Postman/Insomnia o generar un SDK cliente.

Consejos, límites y buenas prácticas

  • Trata todo token o secreto como confidencial; no lo expongas en el front-end ni lo reutilices entre Account/AgentBot, Platform, Widget, MCP y Metrics.
  • Para pruebas, usa una credencial de mínimo privilegio y confirma si la operación es autenticada, pública o un webhook entrante condicionado.
  • Respeta los límites de tasa y maneja los errores 429/5xx con backoff.

Tipos y respuestas en la integración

Use el schema de cada respuesta, además del ejemplo, al generar o validar su cliente:

  • En la agenda, all_day es booleano y los valores de reminders son enteros en minutos.
  • En el perfil, accounts[] incluye el avance de configuración, el identificador del rol de acceso y api_and_webhooks. El objeto access_role aparece solo cuando existe un rol efectivo; los campos condicionados por permisos siguen sujetos a la autorización del servidor.
  • En el Cerebro, signals y suggested_action pueden conservar arrays JSON. No los fuerce a mapas; la lectura y la ocultación de datos siguen los permisos del solicitante.
  • Una inscripción de Follow-up puede responder 422 con error (motivo de rechazo) o con message y attributes (fallo de validación). Lea la variante recibida antes de elegir la siguiente acción.

Solución de problemas

  • La página no abre (404): la documentación puede estar deshabilitada en ese entorno — el operador la habilita con ENABLE_API_DOCS.
  • 401/403 al probar: confirma la superficie y el esquema de seguridad; un api_access_token no autoriza automáticamente Platform, MCP, Metrics ni rutas públicas.
  • Un endpoint no aparece: puede estar fuera de la referencia pública, requerir una fuente curada o pertenecer a la REST separada del operador.

Ver también