Acciones de API personalizadas

Las acciones de API personalizadas permiten que tu agente llame a un endpoint HTTP externo durante una conversación y use la respuesta para responder al visitante. Úsalas para consultar el estado de un pedido, verificar el inventario, obtener detalles de una cuenta o consultar cualquier API interna.

Crear una acción

Ve a Capacidades → Acciones de API personalizadas y haz clic en Agregar acción.

Configuración general

• Nombre — cómo la IA llama a esta acción internamente. Mantenlo corto y descriptivo: Consultar estado del pedido, Obtener disponibilidad del producto.
• Cuándo usar — descripción en inglés simple de cuándo la IA debe activar esta acción.

Usa esta acción cuando el visitante pregunte sobre el estado de su pedido o quiera rastrear un envío.

Configurar la llamada a la API

Método y URL

Selecciona el método HTTP (GET, POST, PUT, PATCH, DELETE) e introduce la URL del endpoint. Usa {{marcadores}} para valores dinámicos:

https://api.tutienda.com/pedidos/{{order_id}}

Entradas de datos

Define las variables que necesitan tu URL, encabezados o cuerpo. Para cada entrada:

Ejemplo para búsqueda de pedido:

• Nombre: order_id · Descripción: El número de pedido proporcionado por el visitante · Obligatorio: sí

La IA extrae valores del contexto de la conversación automáticamente. Si falta un valor obligatorio, la IA se lo pide al visitante antes de hacer la llamada.

Encabezados, parámetros y cuerpo

Usa las pestañas para agregar encabezados de autorización, parámetros de consulta o un cuerpo de solicitud. Los marcadores funcionan en todos lados:

Authorization: Bearer {{api_token}}

Para secretos estáticos (como tokens de API) que no quieres extraer del chat, ingrésalos directamente como valores sin marcador — no serán expuestos a la IA ni a los visitantes.

Probar la acción

En la sección Probar respuesta, introduce valores de ejemplo para tus entradas y haz clic en Ejecutar prueba. Se realiza la llamada HTTP real y se muestra la respuesta. Úsalo para verificar que tu URL y autenticación son correctos antes de activarlos.

Acceso a datos

Controla qué partes de la respuesta de la API puede ver la IA:

• Completo — se pasa a la IA toda la respuesta JSON. Úsalo para respuestas simples donde se necesitan todos los campos.
• Limitado — solo los campos que incluyas en la lista blanca se pasan a la IA. Úsalo para proteger datos sensibles (IDs internos, tokens, PII) de ser incluidos en las respuestas de la IA.

Introduce las rutas de campos, una por línea, usando notación de punto:

order.status
order.estimated_delivery
customer.name

Consejos

• Mantén las respuestas concisas — la IA resume la respuesta al contestar, por lo que una respuesta enfocada da mejores resultados que un objeto de 200 campos.
• Usa el acceso a datos Limitado para cualquier API que devuelva campos sensibles junto a los que necesitas.
• Si tu API requiere OAuth, usa un token de servicio de larga duración en lugar de un token de usuario — la acción se ejecuta en el servidor de BotChata, no en el navegador del visitante.
• La sintaxis {{marcador}} funciona en: ruta URL, parámetros de consulta, encabezados y cuerpo de la solicitud.