API pública de Ventor

Integra Ventor con tus sistemas, agentes y automatizaciones

Usa la API para consultar chats, enviar mensajes, operar plantillas, ejecutar automatizaciones, trabajar con tablas y leer métricas del workspace con permisos controlados por token.

Ver endpoints Crear token

Tokens con permisos

Cada integración recibe solo los scopes que el negocio habilita.

Automatizaciones existentes

Ejecuta flujos ya configurados sin exponer la lógica interna de Ventor AI.

Lista para agentes

Un agente externo puede descubrir capacidades y operar dentro de permisos definidos.

Seccion 1

Inicio rápido

La API usa JSON, tokens Bearer y endpoints versionados bajo /api/public/v1.

Base URL de la API pública:https://api.ventorchat.com/api/public/v1

Crea un token en Ventor

Ve a Avanzado > Integraciones, marca los permisos necesarios y copia el token al crearlo.

Envía el token en cada request

Usa Authorization: Bearer <token>. También se acepta x-ventor-api-key para integraciones que prefieren API key.

Consulta capabilities antes de operar

Ese endpoint devuelve reglas del canal, tablas, plantillas, automatizaciones y capacidades disponibles para el token.

¿Ya tienes una cuenta?

Crea o revoca tokens desde la pantalla de Integraciones.

Crear token

Primer request

curl "https://api.ventorchat.com/api/public/v1/capabilities" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

Conectores visuales de terceros

Los tokens de esta API funcionan en clientes que permiten enviar headers. Algunos conectores visuales, como el custom connector de Claude, requieren OAuth del lado de Ventor en vez de pegar un token manualmente.

Seccion 2

Autenticación y permisos

Un token puede tener todos los permisos o solo los necesarios para una integración específica.

Headers soportados

Authorization: Bearer vtr_live_TU_TOKEN

# Alternativa
x-ventor-api-key: vtr_live_TU_TOKEN

Permiso	Qué habilita
capabilities:read	Leer capacidades y reglas del workspace.
chats:read	Listar chats y leer mensajes.
chats:write	Reactivar el asistente en chats pausados desde MCP, sin enviar mensajes.
messages:write	Enviar mensajes libres o plantillas.
products:read	Consultar estructura, buscar productos y previsualizar enriquecimientos por API o MCP.
products:write	Crear, actualizar o aplicar enriquecimientos confirmados al catálogo por API o MCP.
assistant:read	Leer configuración y participar en el diagnóstico comercial integral desde MCP.
assistant:write	Actualizar configuración del asistente o agregar contexto interno temporal sin mensajes visibles.
templates:read	Listar y usar plantillas aprobadas.
templates:write	Crear o actualizar plantillas.
campaigns:read	Consultar campañas y estados.
campaigns:write	Crear envíos masivos.
tables:read	Leer tablas y filas.
tables:write	Crear o actualizar filas.
automations:read	Listar automatizaciones y consultar ejecuciones.
automations:write	Crear o editar automatizaciones y sus recursos auxiliares mediante el runner administrado de VentorIA por MCP.
automations:run	Ejecutar automatizaciones por API.
metrics:read	Consultar métricas.

Creación y edición conversacional por MCP

automations:write habilita la creación administrada. Con automations:read y automations:write, ventor_edit_automation puede diagnosticar ejecuciones y preparar cambios parciales dentro del runner de VentorIA. La confirmación usa ventor_confirm_automation y el contrato no expone JSON, operaciones internas ni logs crudos. Consulta el flujo completo en la documentación MCP.

Seccion 3

Referencia de endpoints

Todas las rutas de esta tabla se agregan después de la base URL pública.

Método	Ruta	Permiso	Uso principal
GET	/capabilities	capabilities:read	Mapa del workspace, reglas, recursos disponibles y capacidades.
GET	/chats	chats:read	Lista o busca conversaciones. Acepta assistantStatus para distinguir chats activos y pausados.
GET	/chats/{chatUuid}/messages	chats:read	Lee mensajes de un chat con paginación por beforeId, afterId, aroundId y limit.
POST	/chats/{chatUuid}/messages	messages:write	Envía un mensaje libre dentro de una conversación existente.
POST	/chats/{chatUuid}/assistant-context	assistant:write	Agrega datos temporales al contexto interno sin enviar un mensaje al cliente ni disparar una respuesta.
GET	/products/schema	products:read	Devuelve columnas y estructura del catálogo Productos.
GET	/products	products:read	Busca productos por texto, filtros o imagen.
POST	/products/bulk-upsert	products:write	Crea o actualiza hasta 100 productos en una llamada.
GET	/templates	templates:read	Lista plantillas visibles y su estado de aprobación.
POST	/templates	templates:write	Crea o actualiza una plantilla de mensaje.
POST	/templates/{templateId}/send	templates:read + messages:write	Envía una plantilla aprobada con chatUuid o phoneNumber. Con phoneNumber, WhatsApp crea o actualiza el chat cuando Meta acepta el envío.
GET	/campaigns	campaigns:read	Lista envíos masivos con paginación.
POST	/campaigns	campaigns:write	Crea una campaña con plantilla y destinatarios.
GET	/campaigns/{campaignUuid}	campaigns:read	Consulta el detalle y estado de una campaña.
GET	/tables	tables:read	Lista tablas, columnas y estructura disponible.
GET	/tables/{tableUuid}	tables:read	Lee filas de una tabla con limit, offset, search o tag.
POST	/tables/{tableUuid}/rows	tables:write	Crea o actualiza filas de una tabla.
GET	/automations	automations:read	Lista automatizaciones activas y si aceptan ejecución por API.
GET	/automations/{automationUuid}/required-params	automations:read	Obtiene los parámetros requeridos antes de ejecutar una automatización.
POST	/automations/{automationUuid}/run	automations:run	Ejecuta una automatización existente y acepta Idempotency-Key.
GET	/automations/{automationUuid}/runs	automations:read	Lista historial de ejecuciones.
GET	/automations/{automationUuid}/runs/{runUuid}	automations:read	Consulta el detalle de una ejecución.
GET	/metrics/chats	metrics:read	Obtiene métricas de conversaciones por rango o periodo.

Seccion 4

Ejemplos por servicio

Requests base para cada módulo de la API. Reemplaza los UUID, IDs y variables por datos de tu workspace.

Capacidades del workspace

Úsalo como primer request para descubrir canales, reglas, tablas, plantillas, automatizaciones y permisos disponibles.

GET /capabilities

curl "https://api.ventorchat.com/api/public/v1/capabilities" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

Chats y lectura de mensajes

Permite buscar conversaciones y leer el historial de un chat específico.

GET /chats

curl "https://api.ventorchat.com/api/public/v1/chats?q=maria&limit=20&canal=whatsapp" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

GET /chats/{chatUuid}/messages

curl "https://api.ventorchat.com/api/public/v1/chats/chat_uuid/messages?limit=50" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

Mensajes

Envía mensajes libres en conversaciones existentes cuando las reglas del canal lo permiten.

POST /chats/{chatUuid}/messages

curl -X POST "https://api.ventorchat.com/api/public/v1/chats/chat_uuid/messages" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hola, te escribimos desde Ventor."
  }'

Contexto temporal del asistente

Agrega un resultado puntual de una API al contexto interno del chat. No envía mensajes y no reemplaza las tablas relacionadas para datos duraderos.

POST /chats/{chatUuid}/assistant-context

curl -X POST "https://api.ventorchat.com/api/public/v1/chats/chat_uuid/assistant-context" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "API de disponibilidad",
    "context": "La sede Centro tiene 2 cupos disponibles hoy a las 17:00."
  }'

Productos

Descubre la estructura del catálogo, busca productos y crea o actualiza hasta 100 registros por llamada. Para editar, incluye rowId, productId o el campo id existente.

GET /products/schema

curl "https://api.ventorchat.com/api/public/v1/products/schema" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

GET /products

curl "https://api.ventorchat.com/api/public/v1/products?q=departamento+miraflores&limit=10" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

POST /products/bulk-upsert

curl -X POST "https://api.ventorchat.com/api/public/v1/products/bulk-upsert" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "nombre": "Departamento en Miraflores",
        "descripcion": "2 dormitorios, 85 m² y cochera",
        "currency": "USD",
        "precio": 185000,
        "media_urls": ["https://cdn.example.com/inmueble-1.jpg"]
      },
      {
        "nombre": "Casa en La Molina",
        "descripcion": "4 dormitorios, jardín y piscina",
        "currency": "USD",
        "precio": 420000
      }
    ]
  }'

Plantillas

Lista, crea y envía plantillas. En WhatsApp, las plantillas aprobadas son necesarias fuera de la ventana de 24 horas.

GET /templates

curl "https://api.ventorchat.com/api/public/v1/templates" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

POST /templates

curl -X POST "https://api.ventorchat.com/api/public/v1/templates" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "confirmacion_pedido_api",
    "metaTemplate": true,
    "language": "es",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hola {{nombre}}, confirmamos tu pedido {{pedido}}."
      }
    ],
    "variables": [
      { "tag": "nombre", "type": "string", "value": "María" },
      { "tag": "pedido", "type": "string", "value": "A-1042" }
    ]
  }'

POST /templates/{templateId}/send con chatUuid

curl -X POST "https://api.ventorchat.com/api/public/v1/templates/123/send" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatUuid": "chat_uuid",
    "variables": {
      "nombre": "María",
      "pedido": "A-1042"
    }
  }'

POST /templates/{templateId}/send con phoneNumber

curl -X POST "https://api.ventorchat.com/api/public/v1/templates/123/send" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "51999999999",
    "variables": {
      "nombre": "María",
      "pedido": "A-1042"
    }
  }'

Envíos masivos

Crea campañas con plantilla y consulta su estado de ejecución.

GET /campaigns

curl "https://api.ventorchat.com/api/public/v1/campaigns?page=1&limit=20" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

POST /campaigns

curl -X POST "https://api.ventorchat.com/api/public/v1/campaigns" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Confirmación de pedidos",
    "templateId": 123,
    "recipients": [
      {
        "phoneNumber": "51999999999",
        "variables": {
          "nombre": "María",
          "pedido": "A-1042"
        }
      }
    ]
  }'

GET /campaigns/{campaignUuid}

curl "https://api.ventorchat.com/api/public/v1/campaigns/campaign_uuid" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

Tablas

Lee estructuras y filas, o inserta/actualiza registros operativos que Ventor usa en conversaciones y automatizaciones.

GET /tables

curl "https://api.ventorchat.com/api/public/v1/tables" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

GET /tables/{tableUuid}

curl "https://api.ventorchat.com/api/public/v1/tables/table_uuid?limit=50&offset=0&search=maria" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

POST /tables/{tableUuid}/rows

curl -X POST "https://api.ventorchat.com/api/public/v1/tables/table_uuid/rows" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "chatUuid": "chat_uuid",
        "data": {
          "id": "cliente-1042",
          "nombre": "María",
          "telefono": "51999999999",
          "estado": "interesada"
        }
      }
    ]
  }'

Automatizaciones

Lista automatizaciones, revisa parámetros requeridos, ejecuta flujos existentes y consulta historial.

GET /automations

curl "https://api.ventorchat.com/api/public/v1/automations?activeOnly=true" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

GET /automations/{automationUuid}/required-params

curl "https://api.ventorchat.com/api/public/v1/automations/automation_uuid/required-params" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

POST /automations/{automationUuid}/run

curl -X POST "https://api.ventorchat.com/api/public/v1/automations/automation_uuid/run" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN" \
  -H "Idempotency-Key: pedido-A-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "cliente": "María",
      "telefono": "51999999999",
      "monto": 149.9
    }
  }'

GET /automations/{automationUuid}/runs

curl "https://api.ventorchat.com/api/public/v1/automations/automation_uuid/runs?page=1&limit=20" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

GET /automations/{automationUuid}/runs/{runUuid}

curl "https://api.ventorchat.com/api/public/v1/automations/automation_uuid/runs/run_uuid" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

Métricas

Consulta métricas de conversaciones para reportes, dashboards o análisis externos.

GET /metrics/chats

curl "https://api.ventorchat.com/api/public/v1/metrics/chats?period=last_30_days" \
  -H "Authorization: Bearer vtr_live_TU_TOKEN"

Seccion 5

Reglas operativas

Estas reglas evitan errores comunes al automatizar canales conversacionales.

WhatsApp y ventana de 24 horas

Los mensajes libres dependen de la ventana activa. Fuera de la ventana, usa plantillas aprobadas.

Tablas como base operativa

Las tablas vinculadas permiten que el asistente consulte datos actualizados únicamente del chat actual.

Automatizaciones por API

Solo ejecuta automatizaciones existentes. La lógica interna del creador de automatizaciones no se expone por la API.

Idempotencia

Para ejecuciones externas repetibles, envía Idempotency-Key y evita duplicar procesos por reintentos.

Empieza con capabilities

Ese endpoint le da a una integración o agente externo el mapa de lo que puede hacer en el workspace sin revelar secretos internos de Ventor.

Ver inicio rápido