Conecta agentes externos a las herramientas de Ventor

Para trabajar sobre el adaptador sin instalar la versión publicada, apunta directamente al archivo del repositorio.

[mcp_servers.ventor]
command = "node"
args = ["/absolute/path/to/ai-bot-back/ventor-mcp/bin/ventor-mcp.js"]

[mcp_servers.ventor.env]
VENTOR_API_TOKEN = "vtr_live_TU_TOKEN"
VENTOR_API_BASE_URL = "https://api.ventorchat.com"

Para un reporte agregado usa primero ventor_get_crm_funnel_report. Si necesitas un embudo concreto, obtén su funnelUuid con ventor_list_funnels; si lo omites, el reporte incluye las etiquetas independientes y todos los embudos.

Elige dateBasis según la pregunta: first_contact para cuándo ingresó el lead, last_message para el último mensaje del chat o message_activity para cualquier mensaje dentro del periodo. Usa fromDay/toDay para días calendario inclusivos y una zona IANA; usa from/to para instantes ISO, donde el final es exclusivo. No mezcles ambos estilos.

Los conteos representan la etapa actual de los chats que forman la cohorte; no demuestran que hayan cambiado de etapa durante esas fechas. Los detalles de clientes se omiten por defecto. Al usar includeClients: true, el límite es 200 por página global y los conteos siguen siendo completos. Para continuar, envía clientPage.nextCursor como clientCursor con los mismos filtros hasta recibir null; las listas por etapa son el subconjunto de esa página.

Si la pregunta es cuántos entraron, salieron o se movieron entre etapas durante el periodo, usa ventor_get_funnel_stage_history. Esta herramienta consulta eventos reales y devuelve historyAvailableFrom, coverage.complete y coverage.reason, además de asOf y coverage.ongoing. El historial se captura hacia adelante: ningún asistente debe presentar como completo un rango anterior al watermark ni un día que todavía no terminó. Los movimientos ambiguos se cuentan sin inventar una transición.

// Leads que ingresaron del 1 al 7 de agosto y su etapa actual
ventor_get_crm_funnel_report({
  "funnelUuid": "embudo_ventas_uuid",
  "dateBasis": "first_contact",
  "fromDay": "2026-08-01",
  "toDay": "2026-08-07",
  "timezone": "America/Lima",
  "includeClients": false
})

// Actividad en instantes exactos: el final es exclusivo [from,to)
ventor_get_crm_funnel_report({
  "dateBasis": "message_activity",
  "from": "2026-08-01T00:00:00-05:00",
  "to": "2026-08-08T00:00:00-05:00",
  "canal": "whatsapp",
  "includeClients": true,
  "clientLimit": 100
})

// Movimientos reales del 1 al 7 de agosto (toDay es inclusivo)
ventor_get_funnel_stage_history({
  "funnelUuid": "00000000-0000-4000-8000-000000000001",
  "fromDay": "2026-08-01",
  "toDay": "2026-08-07",
  "timezone": "America/Lima"
})

Usa ventor_get_product_schema para descubrir las columnas del catálogo y luego ventor_upsert_products. El agente puede cargar 50 inmuebles en una sola llamada sin pedir acceso de escritura al resto de tablas.

// 1. Descubre las columnas reales del catálogo
ventor_get_product_schema({})

// 2. Crea o actualiza hasta 100 productos en una llamada
ventor_upsert_products({
  "products": [
    {
      "fields": [
        { "columnName": "nombre", "value": "Departamento en Miraflores" },
        { "columnName": "descripcion", "value": "2 dormitorios, 85 m² y cochera" },
        { "columnName": "currency", "value": "USD" },
        { "columnName": "precio", "value": 185000 }
      ]
    },
    {
      "fields": [
        { "columnName": "nombre", "value": "Casa en La Molina" },
        { "columnName": "currency", "value": "USD" },
        { "columnName": "precio", "value": 420000 }
      ]
    }
  ]
})

Antes de cambiar instrucciones, criterios de recomendación o datos de productos, usa ventor_inspect_product_sales_configuration. La inspección combina las fuentes de verdad del asistente, la auditoría del catálogo, el flujo de compra derivado y el inventario de automatizaciones para detectar contradicciones, relaciones sin evidencia y productos sin página de compra.

El negocio describe en lenguaje natural cómo quiere vender. El MCP conserva esa regla en las instrucciones y, si cambia dónde termina la compra, compila internamente solo ese canal en la misma actualización. No le pide al usuario estados, modos ni banderas técnicas; el backend deriva el registro de interés, la reserva de stock, los datos de checkout y la protección del enlace.

El enriquecimiento masivo nunca reemplaza nombre, identidad, precio, stock, disponibilidad, imágenes, URLs ni variantes. Primero llama ventor_preview_product_catalog_enrichment, muestra el resultado y espera una aprobación explícita. Después llama ventor_apply_product_catalog_enrichment con los mismos cambios y el previewToken. Si el catálogo cambió, el backend exige una nueva previsualización.

Por defecto, pulsar Lo quiero confirma interés en el producto principal, pero no acepta ver relacionados. Si el negocio quiere preguntar primero, conserva esa oferta y la espera de un sí explícito en instructions, sin configurar productRecommendationPolicy.onProductSelected.

Solo si el negocio indica expresamente que debe mostrarlos de inmediato sin volver a preguntar, configura el disparador ejecutable en productRecommendationPolicy.onProductSelected. El backend fuerza una sola búsqueda relacionada y conserva las validaciones de relación, estado, stock y límite.

// 1. Reúne configuración, catálogo y automatizaciones sin modificar nada
ventor_inspect_product_sales_configuration({
  "desiredTags": [
    { "tag": "impresora", "aliases": ["equipo de impresión"] },
    { "tag": "consumible", "aliases": ["tinta", "tóner"] }
  ]
})

// 2. Previsualiza únicamente adiciones sustentadas
ventor_preview_product_catalog_enrichment({
  "changes": [
    {
      "rowId": 2107,
      "confidence": "high",
      "evidence": ["Tipo de producto: Impresora"],
      "addTags": ["impresora"],
      "fields": [
        {
          "name": "tipo_producto",
          "mode": "fill_if_empty",
          "value": "impresora"
        }
      ]
    }
  ]
})

// 3. Muestra el preview y espera aprobación explícita.
// Luego usa exactamente los mismos changes y el previewToken recibido:
ventor_apply_product_catalog_enrichment({
  "changes": [/* mismos cambios previsualizados */],
  "previewToken": "preview_token_de_64_caracteres",
  "confirmed": true
})

Usa ventor_build_automation para describir el objetivo en lenguaje natural mediante el parámetro message, no description. VentorIA puede responder con needs_input y una pregunta de negocio, o con needs_confirmation y un resumen. Conserva siempre el sessionId entre turnos.

Si el resumen incluye setupRequirements, muestra cada prerrequisito antes de confirmar. Por ejemplo, una automatización que usa plantillas o formularios de WhatsApp devolverá Conecta WhatsApp cuando el workspace no tenga un canal activo. La propuesta no crea conexiones ni realiza envíos.

Cuando el borrador esté listo, muestra su resumen al usuario. Solo después de recibir una aprobación explícita llama ventor_confirm_automation. Los turnos administrados de creación y edición consumen créditos de VentorIA; la confirmación únicamente guarda la propuesta preparada y no vuelve a llamar al modelo. Revisa también summary.supportingResources: esas tablas o plantillas auxiliares se crearán junto con la automatización.

Para una automatización existente usa ventor_edit_automation. El runner interno carga su definición y, si reportaste un fallo, consulta las ejecuciones necesarias para preparar una corrección puntual. El cliente MCP recibe únicamente el diagnóstico funcional o un resumen confirmable: no recibe JSON, operaciones internas, prompts, credenciales ni logs crudos.

Si Claude u otro cliente ya estaba conectado antes de habilitar este permiso, vuelve a conectarlo para que el consentimiento OAuth incluya automations:write y, para editar, automations:read. Los tokens existentes conservan únicamente los permisos aprobados originalmente.

// 1. Describe el objetivo en lenguaje natural
ventor_build_automation({
  "message": "Cuando ingrese un lead de Lima, avisa al equipo comercial",
  "idempotencyKey": "crear-aviso-leads-lima-01"
})

// Si status = "needs_input", pregunta al usuario y continúa la misma sesión
ventor_build_automation({
  "sessionId": "session_uuid",
  "message": "El aviso debe llegar al equipo comercial",
  "idempotencyKey": "crear-aviso-leads-lima-02"
})

// Si status = "needs_confirmation", muestra summary y espera un sí explícito
ventor_confirm_automation({
  "sessionId": "session_uuid",
  "confirmationId": "confirmation_uuid"
})

// Si devuelve needs_setup, solo con autorización del usuario puedes guardarla
// inactiva para completar luego sus conexiones desde Ventor:
ventor_confirm_automation({
  "sessionId": "session_uuid",
  "confirmationId": "confirmation_uuid",
  "saveAsDraft": true
})

// Diagnostica y prepara un cambio puntual sin recibir el JSON ni los logs
ventor_edit_automation({
  "automationUuid": "automation_uuid",
  "message": "Revisa las ejecuciones fallidas y corrige solo el paso responsable",
  "idempotencyKey": "corregir-automatizacion-01"
})

// Si status = "needs_input", responde en la misma sesión y automatización
ventor_edit_automation({
  "automationUuid": "automation_uuid",
  "sessionId": "session_uuid",
  "message": "Debe reintentar una vez y luego avisar al equipo",
  "idempotencyKey": "corregir-automatizacion-02"
})

// Si status = "needs_confirmation", muestra summary y espera aprobación
ventor_confirm_automation({
  "sessionId": "session_uuid",
  "confirmationId": "confirmation_uuid"
})

Para pagos, pedidos, citas u otros datos por cliente que deban mantenerse actualizados, usa una tabla con chatAssociationEnabled: true y vincula cada fila con chatUuid. ventor_get_capabilities y ventor_list_tables indican assistantReadable: true cuando el asistente del negocio puede consultarla. La lectura siempre queda limitada al chat actual.

Para un resultado puntual ya obtenido por una API, usa ventor_add_assistant_context. No envía nada al cliente y tampoco dispara una respuesta por sí solo: deja el dato disponible para la próxima ejecución del asistente. ventor_send_message siempre es visible.

Dentro de una automatización que atiende el turno actual, el patrón equivalente es consultar la API y pasar su resultado a send_message con mode: assistant y destino {{ChatId}}. Si el dato debe conservarse, actualiza también la tabla relacionada.

// Datos duraderos: vincula cada registro al chat
ventor_upsert_table_rows({
  "tableUuid": "tabla_pagos_uuid",
  "rows": [
    {
      "chatUuid": "chat_uuid",
      "cells": [
        { "columnName": "pago_id", "value": "P-1042" },
        { "columnName": "estado", "value": "confirmado" },
        { "columnName": "monto", "value": 149.9 }
      ]
    }
  ]
})

// Dato temporal: contexto invisible para la próxima ejecución del asistente
ventor_add_assistant_context({
  "chatUuid": "chat_uuid",
  "source": "API de disponibilidad",
  "context": "La sede Centro tiene 2 cupos disponibles hoy a las 17:00."
})

Busca primero con assistantStatus: "paused" y luego usa ventor_resume_assistant_in_chats. No uses ventor_send_message, no edites las instrucciones y no envíes resume_bot: esa cadena no es un comando.

// 1. Verifica primero los chats pausados
ventor_search_chats({
  "assistantStatus": "paused",
  "limit": 50
})

// 2. Reactiva por estado interno, sin enviar mensajes
ventor_resume_assistant_in_chats({
  "scope": "all_paused",
  "allMatching": true,
  "maxChats": 1000
})

ventor_send_template acepta chatUuid para conversaciones existentes o phoneNumber para iniciar el envío directo por WhatsApp. Con chatUuid, Ventor usa siempre el número asociado al chat. Con phoneNumber, consulta primero ventor_get_capabilities para relacionar cada channelId con su número y ventor_list_templates para confirmar que la plantilla esté aprobada en ese canal.

// 1. Antes de un envío a teléfono nuevo, descubre los WhatsApp conectados
ventor_get_capabilities({})
// resources.channels:
// [{ channelId: 45, type: "whatsapp", displayName: "Ventas", phoneNumber: "51911111111", canSendOfficialWhatsapp: true }]

// 2. Verifica que la plantilla esté aprobada para ese channelId
ventor_list_templates({})
// approvedChannelIds: [45]

// Chat existente: no envíes channelId; Ventor usa el WhatsApp del chat
ventor_send_template({
  "templateId": 123,
  "chatUuid": "chat_uuid",
  "variables": [
    { "name": "nombre", "value": "María" },
    { "name": "pedido", "value": "A-1042" }
  ]
})

// Número nuevo: indica el channelId elegido y aprobado
ventor_send_template({
  "templateId": 123,
  "phoneNumber": "51999999999",
  "channelId": 45,
  "variables": [
    { "name": "nombre", "value": "María" },
    { "name": "pedido", "value": "A-1042" }
  ]
})