Herramientas personalizadas HTTP (Custom Tools) en Capitán: cómo conectar APIs externas durante el chat

• Categoría: Agente de IA Capitan
• Disponibilidad: Plan Evolución
• Tiempo estimado de configuración: 25 minutos
• Rol necesario: Administrador

En el Plan Evolución, el Agente de IA Capitán deja de ser únicamente un asistente que consulta documentos estáticos para convertirse en un agente transaccional capaz de interactuar con sistemas en vivo. Desde Capitán → Herramientas, puedes registrar Herramientas personalizadas HTTP (Custom Tools) para que Capitán consulte estados de pedidos en Waclis Tienda, verifique turnos libres en WaclisCAL, valide facturas en Waclis Factur o consulte cualquier API REST externa en mitad de la conversación.

Qué puedes hacer

Desde la sección Capitán → Herramientas (botón + Crear herramienta) puedes dotar a tu asistente de capacidades de ejecución en tiempo real:

• Configurar peticiones HTTP completas (GET, POST, PUT, DELETE): Defines la URL del endpoint y el método HTTP necesario tanto para leer datos en vivo como para enviar registros hacia un servidor externo.
• Autenticar de forma segura las llamadas salientes: Seleccionas el Tipo de autenticación requerido por la API de destino entre Ninguna, Bearer Token, Basic Auth o API Key.
• Definir el Esquema de parámetros que la IA debe recolectar: Especificas qué datos debe extraer Capitán de la charla con el cliente (por ejemplo, numero-pedido, fecha-turno o documento-cliente), indicando su nombre, tipo, descripción y si es obligatorio.
• Armar cargas dinámicas con Plantilla de cuerpo (Liquid): En peticiones POST o PUT, construyes el JSON de salida inyectando los parámetros capturados por el asistente mediante sintaxis Liquid ({{ parametro }}).
• Vincular la herramienta dentro de un Escenario (Herramienta personalizada HTTP): Incrustas tu herramienta personalizada en las Instrucciones de Capitán → Escenarios para controlar exactamente cuándo y cómo se invoca.

Cuándo conviene usarla

Las Herramientas personalizadas HTTP resuelven casos de uso donde la respuesta depende de información dinámica que cambia minuto a minuto:

• Consulta de disponibilidad y agendamiento con WaclisCAL: Cuando un paciente o cliente escribe "¿Tienen turno disponible para mañana a la tarde?" y Capitán consulta en vivo el endpoint de disponibilidad de WaclisCAL antes de ofrecer los horarios reales.
• Seguimiento de pedidos y stock con Waclis Tienda: Cuando un comprador consulta "¿Por dónde va mi pedido #10450?" y el asistente realiza un GET o POST autenticado para informarle el estado logístico sin intervención humana.
• Validación de estado de cuenta o cobertura en sistemas propios: Cuando una empresa de servicios necesita verificar con el DNI o número de cliente si la cuenta está al día antes de habilitar un soporte técnico.

Disponibilidad por plan

La creación y ejecución de Herramientas personalizadas HTTP y conectores avanzados es exclusiva del nivel superior de suscripción:

Requisitos previos

Antes de registrar tu primera herramienta HTTP en Waclis Inbox, verifica estos requisitos:

• Contar con Plan Evolución activo y permisos de Administrador.
• Disponer de la URL HTTPS del endpoint que deseas consultar, su método (GET, POST, PUT o DELETE) y las credenciales de acceso (Bearer Token, Basic Auth o API Key).
• Asegurarte de que el servidor externo responda en formato JSON claro y en menos de 10 segundos para mantener una conversación fluida.

Cómo funciona en Waclis Inbox paso a paso

Paso 1: Crear la herramienta HTTP y definir su autenticación

1. En el menú lateral izquierdo de Waclis Inbox, ingresa a Capitán y selecciona la séptima sección: Herramientas.
2. Haz clic en el botón + Crear herramienta en la esquina superior derecha.
3. Completa la identificación y conexión del servicio:

• Título: asigna un nombre claro (por ejemplo, Consultar Disponibilidad WaclisCAL o Estado de Pedido Waclis Tienda). El sistema generará su identificador interno Herramienta personalizada HTTP.
• Descripción: explica qué hace la herramienta y qué devuelve (por ejemplo, "Consulta los horarios libres en WaclisCAL para una fecha determinada").
• URL del endpoint: ingresa la dirección HTTPS del servicio.
• Método HTTP: selecciona GET, POST, PUT o DELETE.
• Tipo de autenticación: elige Ninguna, Bearer Token, Basic Auth o API Key y carga la credencial correspondiente.

Paso 2: Configurar el Esquema de parámetros y la Plantilla Liquid

1. En la sección Esquema de parámetros, añade cada variable que Capitán debe obtener de la conversación antes de ejecutar la llamada HTTP:

• nombre: identificador de la variable sin espacios (por ejemplo, numero-pedido o fecha-consulta).
• tipo: tipo de dato (string, number, boolean).
• descripción: instrucción para que el LLM sepa cómo extraer el dato (por ejemplo, "Fecha solicitada por el cliente en formato YYYY-MM-DD").
• obligatorio: marca esta casilla si Capitán debe repreguntarle el dato al usuario en caso de que no lo haya mencionado aún.

1. Si elegiste el método POST o PUT, completa el campo Plantilla de cuerpo (Liquid) utilizando las variables definidas en el esquema, por ejemplo:

{"pedido": "{{ numero-pedido }}", "fecha": "{{ fecha-consulta }}"}

1. Haz clic en Crear / Guardar para registrar la herramienta.

Paso 3: Vincular la herramienta en un Escenario y probar en Playground

1. Dirígete a Capitán → Escenarios y crea o edita el escenario correspondiente (por ejemplo, Reserva de Turnos o Consulta de Envío).
2. En el campo Instrucciones, referencia tu nueva herramienta usando el formato Nombre de la herramienta, indicando qué hacer con la respuesta devuelta.
3. Abre Capitán → Playground, simula la solicitud de un cliente y verifica en el inspector de herramientas que Capitán pide el parámetro obligatorio, ejecuta la llamada HTTP y redacta la contestación con los datos reales devueltos por la API.

Opciones y configuraciones disponibles

Alternativas y cuándo elegir cada una

Cómo se combina con otras funciones

• Escenarios y Handoff condicional: En Capitán → Escenarios, puedes instruir a Capitán para que ejecute Herramienta personalizada HTTP y, si el JSON devuelto indica que el envío está "demorado", agregue una nota privada (Añadir nota privada) y transfiera el caso a un humano (Transferir a un agente humano).
• Servidores MCP (Capitán > Servidores MCP): Si tu infraestructura expone un servidor bajo el estándar Model Context Protocol, puedes conectarlo en la sección vecina Servidores MCP para descubrir múltiples herramientas de forma simultánea.

Relación con otros productos Waclis

• Funciones nativas de Waclis Inbox: El motor de extracción de parámetros, el renderizado de plantillas Liquid y el cliente HTTP seguro de Capitán → Herramientas corren de forma nativa dentro de Waclis Inbox.
• Orquestación en vivo con WaclisCAL, Waclis Tienda y Waclis Factur: A través de los contratos de API de Waclis Connect, las herramientas personalizadas permiten que Capitán consulte disponibilidad de agenda en WaclisCAL, estados de órdenes o catálogo en Waclis Tienda y comprobantes en Waclis Factur respetando el aislamiento multi-tenant de tu organización.

Buenas prácticas

Errores frecuentes y solución de problemas

Preguntas frecuentes

¿Puedo usar variables en la URL en peticiones de tipo GET?

Sí. Puedes definir los parámetros en el Esquema de parámetros para que Capitán los capture durante la conversación y los envíe en la consulta hacia tu endpoint HTTP.

¿Mis clientes pueden ver el Token o la API Key configurada en la herramienta?

No. Las credenciales cargadas en Tipo de autenticación se almacenan de forma segura en el servidor de Waclis Inbox y las llamadas HTTP se realizan de servidor a servidor (backend a backend), sin exponerse jamás en el navegador ni en el chat del cliente.

¿Qué pasa si el cliente aún no dijo su número de pedido cuando se activa el escenario?

Si marcaste el parámetro numero-pedido como obligatorio en el Esquema de parámetros, Capitán pausará la ejecución de la herramienta, le pedirá primero el número de pedido al cliente y, apenas este responda, ejecutará la llamada HTTP automáticamente.

¿Dónde puedo probar si mi herramienta HTTP funciona antes de activarla en WhatsApp?

Siempre en Capitán → Playground. El simulador ejecuta las llamadas HTTP reales configuradas en tu herramienta y te muestra los parámetros enviados y la respuesta obtenida sin afectar ningún canal público.

Artículos relacionados

• Escenarios y directivas de respuesta especializada en el Agente de IA Capitan
• Integración nativa con Waclis Tienda y Waclis Factur
• Webhooks salientes, Aplicaciones de Panel y API de Plataforma