Acciones API propias: llama a tu API desde el chat

Una acción API propia permite que el agente llame a un endpoint HTTP mientras conversa, por ejemplo para consultar existencias o precios actuales, y responda a partir del resultado. Las acciones se crean en la pestaña Actions (acciones) de tu agente. Para que el agente ofrezca un enlace en lugar de llamar a una API, consulta Botones personalizados.

Crear una acción

Haz clic en Add Action, o en Import a request para empezar desde un comando cURL. El editor tiene cuatro pasos y se guarda una sola vez al final con Create action. La prueba es opcional pero recomendable.

1. The request (la petición)

• Method: GET, POST, PUT, PATCH o DELETE.
• HTTPS URL: el endpoint. Una cadena de consulta pegada en la URL pasa a la pestaña Parameters.
• Parameters, Headers y Body admiten pares de clave y valor. Body está disponible en todos los métodos salvo GET y se envía como JSON.
• Collect data inputs for action (optional): valores que el agente obtiene de la conversación. Cada dato tiene un Name (letras, números y guiones bajos), un Type (Text, Number o Boolean), una Description y las opciones Required y Array. Hasta 25 datos por acción.

Usa un dato en cualquier parte de la petición como {{name}}: en la ruta de la URL, un parámetro, una cabecera o el cuerpo.

GET https://api.example.com/products/{{productId}}/stock

El agente encuentra el valor en la conversación o se lo pide al visitante. Un dato Required impide que el agente llame a la acción antes de tener ese valor. Las variables que se usan pero no están declaradas como datos se eliminan de la petición; el editor te avisa y ofrece Add them.

Autenticación

Importar una petición

Pega el ejemplo cURL de la documentación de tu API, o usa «Copy as cURL» sobre una petición en las herramientas de red del navegador. Se rellenan método, URL, parámetros, cabeceras y cuerpo, y la credencial pasa al selector Authentication. Importar sustituye la petición pero conserva el nombre y la descripción. Las subidas multipart (-F) se omiten y un cuerpo codificado como formulario se importa como campos JSON.

2. Try it (probar)

Introduce valores de prueba para los datos y haz clic en Send test request. La petición se construye exactamente como la construirá el agente. Response Preview muestra el estado, el cuerpo de la respuesta y la URL llamada.

3. When the AI should use it (cuándo usarla)

• Action Name: hasta 60 caracteres.
• When to use: qué hace la acción, qué datos devuelve y ejemplos de preguntas que deben activarla. El modelo lee los primeros 1.024 caracteres.
• Server-side action se ejecuta en los servidores de intoCHAT y es la opción predeterminada. Client-side action se ejecuta en el navegador del visitante; consulta Acciones del lado del cliente.
• Enable this action: desactiva una acción sin borrarla.

4. What the AI can see (qué ve la IA)

Full data access pasa toda la respuesta al modelo. Limited data access pasa solo los campos que marques en Visible; ejecuta antes una prueba para cargar la lista de campos. Si la respuesta es una lista, los campos se leen del primer elemento y el filtro se aplica a todos. Mientras no marques ningún campo, se pasa la respuesta completa.

Límites y seguridad

• Hasta 25 acciones por agente, incluidos los botones personalizados y las acciones que crea Conecta tu tienda.
• La URL debe apuntar a un host público. Se rechazan localhost, redes privadas, direcciones link-local y endpoints de metadatos de la nube, también cuando un nombre de host se resuelve en una de ellas. El editor muestra entonces «URL points to a blocked or internal host».
• No se siguen redirecciones. Si la prueba muestra «This address redirects somewhere else», haz clic en Use this address.
• Cada llamada caduca a los 30 segundos.
• Las respuestas de más de 40.000 caracteres se recortan. Con Limited data access se mantienen pequeñas.
• Las acciones del lado del servidor envían tus credenciales desde los servidores de intoCHAT, nunca a través del navegador del visitante.