API Connect

¿Para qué sirve?

La acción API Connect (nombre técnico api_connect) permite que el bot recopile datos del usuario en varios turnos de conversación, llame a una o más APIs HTTP externas con esos datos y entregue el resultado al LLM para que responda con información real: consultas de pedidos, seguimiento de envíos, validaciones, disponibilidad de productos, etc. Comparte la misma infraestructura conversacional que Recolección de datos: campos configurables, frases de opt-out en campos opcionales, frases de salida para abandonar el flujo, mensaje de bienvenida y mensaje de cierre.

Características principales

• Cuatro modos de captura: field_by_field (campo a campo), hybrid (híbrido con LLM), route_by_value (enrutar por valor) y chain (API en cadena).
• Múltiples rutas API configurables por intención: URL, método HTTP, headers, parámetros de query y cuerpo JSON.
• Placeholders {{nombreCampo}} en URL y mappings para inyectar los datos recopilados.
• Validación local de campos: texto, email, teléfono, URL, número; regex, rango de dígitos, mín/máx numérico.
• Mensaje de bienvenida y mensaje de cierre obligatorios; frases de salida y opt-out configurables.
• Modo chain: varias APIs en secuencia con ramificación tras cada respuesta HTTP.
• Respuesta directa estable (direct_reply) además de la respuesta generada por el LLM, para mensajes de éxito o error predecibles.

Configuración en el dashboard

En el dashboard, al editar una intención, elige la acción Conectar API. Configura el modo de captura, las tarjetas de API (rutas), los campos a pedir, los mensajes de bienvenida/cierre y, si aplica, las reglas de inicio y transiciones en modo cadena. La guía detallada de modos, rutas y chain está más abajo en esta misma página.

Flujo en el sistema

Usuario escribe → se detecta la intención → el bot inicia la recolección conversacional (pide campos según el modo) → cuando hay datos suficientes, el sistema selecciona la ruta API (según modo) → realiza la llamada HTTP → interpreta la respuesta → inyecta el resultado en el contexto del LLM → el bot responde al usuario con la información obtenida.

Ejemplo: consulta de estado de pedido (campo a campo)

Configuras una intención con frases como “¿dónde está mi pedido?” o “consultar mi orden”. La acción API Connect pide el código de pedido (campo obligatorio con validación de 7 dígitos). El usuario responde “es el 1234567” y el bot acepta el valor aunque venga en una frase completa. El sistema llama a POST https://api.tutienda.com/orders/status con {"orderId": "1234567"}, recibe el JSON con el estado y el LLM responde: “Tu pedido 1234567 está en camino; llegará el jueves.” Si la API devuelve error, el bot usa el mensaje de error configurado o interpreta el error_response_example.

Modos de captura

El modo de captura (capture_mode) define cómo el bot recopila los datos del usuario y cuándo elige qué API llamar. Eliges uno al configurar la intención en el dashboard.

Enrutar por valor vs API en cadena

Es la distinción más importante:

• Enrutar por valor — el branching ocurre antes de la llamada HTTP, según el mensaje o dato del usuario. Solo se ejecuta una API por flujo.
• API en cadena — el branching ocurre después de cada respuesta HTTP. Pueden ejecutarse varias APIs en secuencia; la salida de un paso alimenta el siguiente.

Campos a pedir (form_data)

Los campos se configuran en la sección Campos a pedir del modal de intención (igual que en Recolección de datos). Cada campo tiene:

• Nombre — identificador usado en placeholders ({{nombreCampo}}) y en condiciones de enrutado.
• Tipo — text, email, phone, url, number.
• Obligatorio u opcional — los opcionales pueden saltarse con frases de opt-out.
• Validaciones — regex (pattern), rango de dígitos (min_digits, max_digits), mín/máx numérico, integer_only.

El bot pide los campos de forma conversacional: acepta el valor aunque venga dentro de una frase (“mi código es 1234567”). También puedes configurar:

• Frases de opt-out — para que el usuario omita un campo opcional (“prefiero no darlo”, “saltar”).
• Frases de salida — para abandonar el flujo completo (“cancelar”, “mejor no”, “salir”).

Tarjetas de API (rutas)

Cada intención API Connect tiene una o más rutas (routes[]), una tarjeta por API. Campos principales:

• route_id — identificador único de la ruta (obligatorio).
• URL — endpoint; admite placeholders como https://api.ejemplo.com/orders/{{orderId}}.
• Método HTTP — GET, POST, PUT, PATCH, DELETE.
• Timeout — entre 2 y 120 segundos (por defecto 15).
• Headers — cabeceras estáticas en JSON (p. ej. Authorization).
• Query mapping — parámetros de URL; valores pueden ser {{campo}} o el nombre del campo.
• Body mapping — cuerpo JSON para POST/PUT/PATCH. Si está vacío, se envía todo el diccionario de respuestas recopiladas.
• Response example — JSON de ejemplo de respuesta exitosa; el LLM lo usa para interpretar el resultado.
• Error response example — JSON de ejemplo de error; ayuda a construir la respuesta directa al usuario.
• Mensajes opcionales — éxito, error y “sin coincidencia de ruta” por tarjeta.

En modos distintos de chain, cada tarjeta puede tener una condición (when) para decidir si esa ruta aplica. En modo chain, esa condición en la tarjeta se ignora; las ramas van en transitions (ver API en cadena).

Condiciones de enrutado (v1)

Las condiciones (when) determinan qué ruta o transición aplica. Tipos soportados hoy:

• always — siempre coincide (útil como regla por defecto).
• regex — campo + patrón; el valor debe coincidir con el patrón completo (re.fullmatch).
• digits_range — campo + min_digits y max_digits; cuenta solo dígitos (ignora letras y símbolos).

Orden de evaluación:

1. Se evalúan las reglas en orden; gana la primera que coincide.
2. Si ninguna coincide, se usa la fila marcada como default (is_default: true).
3. Si tampoco hay default → error o mensaje configurado (route_no_match_message / flow_no_path_message).

API en cadena (chain)

El modo API en cadena ejecuta varias APIs en secuencia. La rama se decide después de cada respuesta HTTP, no con el mensaje inicial en paralelo.

Flujo resumido

1. Se detecta la intención y se recopilan los datos del usuario.
2. Reglas de inicio (start_rules) eligen el primer paso según los datos ya recopilados (antes del primer HTTP).
3. Se llama a la primera API; se extraen variables de la respuesta.
4. Transiciones (transitions) eligen el siguiente paso, el fin exitoso o el fin con error.
5. Se repite hasta __finish__, __finish_error__ o agotar el flujo.

Reglas de inicio (start_rules)

Se evalúan una sola vez, cuando ya hay datos del usuario, antes de la primera llamada HTTP. Ejemplo: código de 5 dígitos → paso “lookup”; código de 9+ dígitos → paso “tracking”.

Fallbacks si ninguna regla coincide:

• start_default_route_id — paso por defecto.
• entry_route_id — respaldo legacy de API de inicio.

Campos por paso (chain)

• step_fields — qué campos pedir antes de ejecutar ese paso.
• response_mapping — extraer variables del JSON de respuesta con notación de punto (data.orderId, data.type).
• response_extract_llm — extracción adicional con LLM del cuerpo de respuesta (opcional).
• stop_on_error — si es true (por defecto), un HTTP fallido detiene la cadena.
• transitions — reglas post-respuesta con next_route_id.

Destinos especiales en transiciones

• "api_order" (u otro route_id) — saltar a ese paso.
• __finish__ — terminar la cadena con éxito.
• __finish_error__ — terminar la cadena con error controlado.

flow_no_path_message — mensaje al usuario si ninguna transición coincide y no hay default.

Límites de seguridad: máximo 10 pasos API por turno del usuario y 20 pasos totales por sesión de chain.

Ejemplo mínimo (lookup → detalle de pedido)

{
  "capture_mode": "chain",
  "entry_route_id": "lookup",
  "start_rules": [
    {
      "label": "Código corto",
      "when": { "type": "digits_range", "field": "code", "min_digits": 5, "max_digits": 5 },
      "start_route_id": "lookup"
    }
  ],
  "flow_no_path_message": "No pude decidir el siguiente paso.",
  "routes": [
    {
      "route_id": "lookup",
      "endpoint_url": "https://api.ejemplo.com/lookup/{{code}}",
      "step_fields": ["code"],
      "response_mapping": { "entityType": "data.type", "orderId": "data.orderId" },
      "transitions": [
        { "label": "Es orden", "when": { "type": "regex", "field": "entityType", "pattern": "^ORDER$" }, "next_route_id": "order_detail" },
        { "label": "Default", "is_default": true, "next_route_id": "__finish_error__" }
      ]
    },
    {
      "route_id": "order_detail",
      "endpoint_url": "https://api.ejemplo.com/orders/{{orderId}}",
      "transitions": [
        { "label": "Fin", "when": { "type": "always" }, "next_route_id": "__finish__" }
      ]
    }
  ]
}

Casos de uso

1. Consulta simple (campo a campo)

Intención “¿dónde está mi pedido?”. Modo field_by_field. Un campo orderId obligatorio. Una ruta POST a la API de tu tienda. El bot pide el código, llama a la API y responde con el estado.

2. Tracking vs pedido (enrutar por valor)

Intención “consultar mi envío o pedido”. Modo route_by_value. El usuario da un solo código. Si tiene 8–12 dígitos → API de tracking; si empieza por ORD- → API de pedidos. Solo se ejecuta una API según el formato.

3. Lookup en cadena (chain)

Intención “buscar información de un código”. Modo chain. Primera API identifica si el código es pedido, cliente o producto. Segunda API trae el detalle según el tipo detectado. El usuario recibe una respuesta unificada con toda la información.

Limitaciones actuales (v1)

Para evitar expectativas incorrectas al configurar intenciones:

• No hay editor visual de flujo (canvas); la cadena se configura con tarjetas y tablas en el modal.
• Las condiciones v1 no incluyen http_status ni json_equals; solo always, regex y digits_range.
• En modo chain no hay ejecución paralela de ramas; siempre es secuencial paso a paso.