Acciones

#Crear acciones

Crea acciones desde Configuración del chatbot → Acciones. Cada acción necesita:

• Nombre — Un identificador corto que la IA usa para decidir cuándo llamarla (p. ej., "consultar pedido")
• Descripción — Explica a la IA cuándo debe usarse esta acción
• URL del endpoint — La URL HTTPS a llamar
• Método HTTP — GET, POST, PUT, PATCH o DELETE
• Cabeceras personalizadas — Tokens de autorización u otras cabeceras

#Parámetros

Las acciones pueden aceptar parámetros que se pasan a tu endpoint. Cada parámetro tiene un nombre, tipo y fuente.

Tipos de parámetros

• string — Texto libre
• number — Valor numérico
• boolean — Verdadero o falso
• enum — Uno de un conjunto predefinido de valores

Fuentes de parámetros

• customer — Recopilado por la IA de la conversación (p. ej., "¿Cuál es tu número de pedido?")
• context — Extraído del contexto de la conversación automáticamente
• system — Inyectado en el servidor (p. ej., el ID del cliente) — nunca expuesto al usuario

#Formato de la solicitud

Cómo se envían los parámetros depende del método HTTP:

• GET, DELETE — Los parámetros se añaden como cadenas de consulta
• POST, PUT, PATCH — Los parámetros se envían en un cuerpo JSON

Ejemplo: solicitud POST

1
2
3
4
5
6
7
POST https://api.acme.com/actions/create-ticket

{
  "subject": "Pregunta sobre facturación",
  "priority": "high",
  "customerId": "cus_12345"
}

Ejemplo: solicitud GET

1
2
GET https://api.acme.com/actions/order-status
  ?orderId=4521

#Confirmación del cliente

Activa Requiere confirmación en una acción para que el chatbot solicite la aprobación del cliente antes de ejecutarla. Esto es útil para operaciones destructivas o sensibles, como cancelar un pedido o actualizar datos de la cuenta.

Cuando se requiere confirmación, la IA presentará la acción y los parámetros recopilados al cliente y esperará la aprobación explícita antes de realizar la llamada a la API.

#Pruebas

Cada acción tiene un botón de Probar que te permite ejecutarla con valores de argumento de muestra. El resultado de la prueba muestra:

• Código de estado HTTP y tiempo de respuesta
• El cuerpo de la respuesta de tu endpoint
• Cualquier error (timeouts, fallos de conexión, URLs no válidas)

#Seguridad

• Solo HTTPS — Los endpoints de acciones deben usar HTTPS (HTTP es rechazado)
• IPs privadas bloqueadas — Localhost, rangos de IPs privadas y endpoints de metadatos son rechazados
• Tiempo de espera — Las solicitudes expiran tras 10 segundos por defecto (configurable de 1-30s)
• Truncamiento de respuestas — Las respuestas de más de 4.000 caracteres se truncan para evitar la explosión de tokens en el contexto de la IA
• Ejecución en el servidor — Todas las llamadas a la API ocurren de servidor a servidor desde la infraestructura de CustomerHero, nunca desde el navegador