Saltearse al contenido
Atendium ISO

API Rest (Custom Request)

La herramienta API Rest (Custom Request) es indiscutiblemente una de las más importantes y potentes del ecosistema Atendium. Con los conocimientos técnicos adecuados, los usuarios pueden extender el funcionamiento total de su agente mediante el protocolo MCP, permitiendo la integración con cualquier sistema externo que disponga de APIs. Esta capacidad transforma a tu agente de IA en un sistema completo y robusto de automatización de extremo a extremo.

¿Qué permite hacer?

Con esta herramienta, el agente puede realizar llamadas HTTP completas:

  • Métodos soportados: GET, POST, PUT, DELETE, PATCH.
  • Configuración dinámica: Podés definir URLs, cabeceras (headers) y cuerpos de mensaje (body) personalizados.
  • Autenticación: Soporta el envío de tokens y parámetros de seguridad.

Configuración de Parámetros y Variables

Podés configurar variables personalizadas en tres secciones de la petición: URL (Query String), Headers y Body. Para cada variable, tenés tres formas de definir su valor:

  1. Valor Estático: Un texto fijo que siempre se envía (ej: una API Key).
  2. Deducido por IA (@AI): El agente intentará extraer el dato de la conversación.
  3. Variable de Sistema: Datos automáticos como el ID del usuario.

Gestión de Parámetros Dinámicos

Cuando definís una variable que debe ser interpretada por la IA, podés configurar su comportamiento:

  • Mandatorio (Obligatorio): El agente pausará la ejecución y le pedirá el dato al usuario si no lo tiene (ej: “¿Cuál es tu número de pedido?”).
  • Opcional: El agente intentará enviarlo si aparece en la charla, pero si no está, realizará la petición de todas formas.

Inyección de Lógica con @AI()

Esta es la funcionalidad más potente. Podés usar la nomenclatura @AI("instrucción") directamente en los campos de configuración o enviar un objeto JSON completo para que la IA deduzca las claves y valores necesarios.

Ejemplo en el Body (JSON):

{
  "tracking_number": "@AI(Extrae el número de seguimiento)",
  "postal_code": "@AI(Pide el código postal si no lo dijo)",
  "metadata": "@AI(Deduce este objeto JSON basándote en lo que el usuario necesita)"
}

Nomenclatura Inteligente

Si enviás un objeto JSON en el body, podés simplemente nombrar las variables de forma descriptiva y la IA usará su capacidad de razonamiento para mapear la conversación al esquema JSON que definas.

Seguridad y Credenciales

La herramienta permite vincular Credenciales previamente creadas en el panel de Atendium. Esto asegura que tus tokens de acceso o API Keys no queden expuestos y sean manejados de forma segura por el servidor al realizar las peticiones.

Casos de Uso Avanzados

  • Consulta de Tracking: Conectá el bot con tu proveedor de logística para informar estados de envío.
  • Validación de Usuarios: Verificá si un cliente existe en tu propia base de datos mediante su DNI o email.
  • Activación de Procesos: Dispará un proceso en tu servidor interno (ej: generar una factura o activar un servicio) cuando el agente cierre una venta.

Limitación de Respuestas

La API externa debe responder en formato JSON. Si la respuesta contiene demasiada información, el agente intentará resumirla para el usuario, pero es recomendable que la API devuelva solo los datos esenciales para una mejor experiencia.

Estructura de Metadata (Payload)

Si habilitás el envío de metadatos, tu endpoint recibirá un objeto metadata que permite identificar el contexto exacto de la petición. Esto es vital para sistemas que necesitan saber quién habla o desde qué canal.

Ejemplo de estructura recibida:

{
  "metadata": {
    "agent_id": "ID único del agente",
    "agent_type": "web | whatsapp | instagram | telegram",
    "channel_id": "ID de la conexión específica",
    "to": "Identificador del destinatario (ej: número de teléfono)",
    "session_id": "ID de la sesión de chat actual",
    "is_training_mode": true,
    "time_zone": "America/Argentina/Buenos_Aires"
  },
  "tu_propio_body": { ... }
}

Campos Clave:

  • agent_id: Permite diferenciar entre múltiples bots si usás un solo endpoint para varios clientes.
  • to: Este es el identificador del usuario final. En WhatsApp es su número de teléfono, en Web es un ID de sesión anónimo.
  • is_training_mode: Indica si la prueba se está haciendo desde el “Test Center” (true) o si es un mensaje de un cliente real (false).
  • time_zone: Útil para dar respuestas basadas en la hora local del usuario.