Guía de configuración de AI Actions con ejemplos

Guía de Configuración de Acciones de IA con Ejemplos

Las Acciones de IA permiten que el chatbot llame a tus APIs externas para obtener datos en tiempo real o realizar operaciones durante una conversación. En lugar de respuestas genéricas, el bot puede consultar pedidos, verificar el estado de la cuenta o activar flujos de trabajo.

Cómo Funcionan las Acciones de IA

1. Un cliente pregunta algo como "¿Cuál es el estado de mi pedido?"
2. La IA determina qué acción llamar en función de la descripción de la acción.
3. La IA extrae parámetros de la conversación (por ejemplo, número de pedido).
4. Helpium llama a tu endpoint de API con esos parámetros.
5. La IA formatea la respuesta en un mensaje útil.

Creando una Acción

Ve a Configuración → Integraciones → Acciones de IA y haz clic en Nueva Acción.

Campos Requeridos

• Nombre: Un nombre descriptivo (por ejemplo, "Consultar Estado del Pedido")
• Slug: Identificador amigable para URL, generado automáticamente a partir del nombre
• Descripción: Indica a la IA cuándo usar esta acción. ¡Sé específico! Ejemplo: "Devuelve el estado actual y la información de seguimiento de un pedido del cliente. Usar cuando un cliente pregunte sobre el estado del pedido, envío o entrega."
• URL: La URL de tu endpoint de API
• Método HTTP: GET, POST, PUT o DELETE

Tipos de Autenticación

Tipo	Descripción	Caso de Uso
Ninguno	Sin autenticación	Endpoints públicos
API Key	Envía un token estático en un encabezado	Llamadas de servidor a servidor
Customer Bearer	Envía el token de Sanctum del cliente	Endpoints de usuario autenticado

Customer Bearer es poderoso: permite que la IA actúe en nombre del cliente que ha iniciado sesión, llamando a tu API con su token de autenticación. El cliente debe ser identificado a través de Helpium.identify({ bearerToken }) para que esto funcione.

Parámetros

Define las entradas que la IA debe extraer de la conversación:

• Nombre: Nombre del parámetro enviado a tu API
• Tipo: cadena, número o booleano
• Requerido: Si la IA debe tener este valor antes de llamar
• Descripción: Ayuda a la IA a entender qué extraer. Ejemplo: "El número de pedido, generalmente comienza con ORD-"

Ejemplo 1: Consulta de Estado del Pedido (Autenticación por API Key)

Nombre: Consultar Estado del Pedido
Slug: consultar-estado-del-pedido
Descripción: Devuelve el estado actual y la información de seguimiento de un pedido del cliente.
             Usar cuando un cliente pregunte sobre el estado de su pedido, envío o cronograma de entrega.
URL: https://api.tutienda.com/pedidos/{numero_pedido}
Método: GET
Tipo de Autenticación: API Key
Encabezado de Autenticación: X-API-Key
Token de Autenticación: tu_api_key_de_tutienda

Parámetros:
  - numero_pedido (cadena, requerido): El número de pedido, típicamente comienza con ORD-

Ejemplo 2: Saldo de Cuenta (Autenticación por Customer Bearer)

Nombre: Consultar Saldo de Cuenta
Slug: consultar-saldo-de-cuenta
Descripción: Devuelve el saldo actual de la cuenta del cliente y las transacciones recientes.
             Usar cuando un cliente pregunte sobre su saldo, créditos o cargos recientes.
URL: https://app.tuservicio.com/api/cuenta/saldo
Método: GET
Tipo de Autenticación: Customer Bearer
No se necesitan parámetros: el token bearer identifica al cliente.

Ejemplo 3: Cancelar Suscripción (Autenticación por Customer Bearer)

Nombre: Cancelar Suscripción
Slug: cancelar-suscripcion
Descripción: Cancela la suscripción activa del cliente. Usar solo cuando el cliente
             confirme explícitamente que desea cancelar. Siempre confirmar antes de llamar.
URL: https://app.tuservicio.com/api/suscripcion/cancelar
Método: POST
Tipo de Autenticación: Customer Bearer
Parámetros:
  - motivo (cadena, opcional): El motivo de la cancelación

Mejores Prácticas

• Escribe descripciones claras. La IA utiliza la descripción para decidir cuándo llamar a la acción. Descripciones vagas conducen a un uso incorrecto.
• Usa autenticación Customer Bearer para datos personalizados. Es más seguro que pasar IDs de usuario como parámetros.
• Establece tiempos de espera apropiados. El predeterminado es de 10 segundos. Aumenta para endpoints lentos, disminuye para consultas simples.
• Prueba a fondo. Usa el botón de prueba en la página de configuración de cada acción para verificar que funcione antes de habilitarlo.
• Comienza simple. Empieza con acciones de solo lectura (GET) antes de agregar acciones que modifiquen datos (POST/PUT/DELETE).