Saltar al contenido
Documentación

Acciones API propias: llama a tu API desde el chat

Haz que tu agente intoCHAT llame a tu API HTTP durante el chat: petición y autenticación, importar cURL, datos tomados de la conversación y prueba.

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.

Marcadores para visitantes verificados

Con la verificación de identidad configurada, una acción del lado del servidor también puede usar {{user.id}}, {{user.email}}, {{user.name}} y {{user.metadata.<key>}} en la URL, los parámetros, las cabeceras y el cuerpo:

GET https://api.example.com/customers/{{user.id}}/orders

No son datos: intoCHAT los rellena en sus servidores a partir del visitante que tu web identificó y verificó, y los deja vacíos para todos los demás y en Send test request. La IA nunca los ve y no puede elegirlos. Cualquier otro marcador {{user.…}} no se puede guardar. Consulta Marcadores en las acciones del lado del servidor.

Marcadores para contactos

Una acción del lado del servidor también puede leer el contacto del visitante: {{contact.email}}, {{contact.name}}, {{contact.phone}}, {{contact.external_id}} y {{contact.<attribute>}}, como {{contact.plan}}:

GET https://api.example.com/accounts/{{contact.external_id}}?plan={{contact.plan}}

Para un visitante verificado es el contacto con su ID de usuario; para cualquier otra persona, el contacto del lead guardado en la conversación, salvo que ese contacto tenga un ID externo. intoCHAT los rellena en sus servidores y la IA nunca los ve. A diferencia de {{user.*}}, no se envía nada vacío: si no hay contacto o falta un valor, la acción no se ejecuta y al agente se le dice que no puede hacerlo aquí. Los marcadores desconocidos como {{contact.Plan}} no se pueden guardar, Send test request no puede rellenarlos y las acciones del lado del cliente nunca los reciben. Consulta Usar los contactos en las acciones.

Autenticación

OpciónQué se envía
No authenticationNada
Bearer token / access tokenUna cabecera Authorization: Bearer con tu token
API key in a headerTu clave en la cabecera que indiques, por ejemplo X-API-Key
API key in the URLTu clave como parámetro de consulta con el nombre que indiques, por ejemplo api_key
Username and passwordAutenticación HTTP básica
Custom — I'll set the headers myselfLo que añadas en la pestaña Headers

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.
  • Only inside procedures (solo acciones del lado del servidor): el agente solo puede llamar a la acción en un paso de un procedimiento que la llama, nunca por su cuenta. Una llamada en cualquier otro momento se rechaza y no se envía nada. Úsalo para acciones que cambian algo, como un reembolso. La acción muestra entonces la etiqueta Procedure only en la lista.
  • Requires team approval (solo acciones del lado del servidor, Pro y Enterprise): cuando el agente llama a la acción, todavía no se envía nada. La llamada, con sus entradas, espera en la página Approvals hasta que alguien que puede editar este agente la aprueba (entonces se ejecuta exactamente con esas entradas) o la rechaza, y al visitante se le comunica el resultado en el chat. Elige cuándo caduca una petición sin decidir: 1 hora, 4 horas, 24 horas o 3 días. La acción muestra la etiqueta Needs approval en la lista. Consulta Aprobación del equipo para acciones.

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.
  • Los formularios de chat, los procedimientos, las Reservas con Cal.com o Calendly y la búsqueda web no cuentan para ese límite.
  • Una acción a la que llama un paso de un procedimiento no se puede borrar ni convertir en una acción del lado del cliente o un botón hasta que la quites del procedimiento. El mensaje indica los procedimientos.
  • Una acción API o un botón cuyo nombre coincide con el de una herramienta integrada, como «search web» o «show booking slots», se renombra internamente con un número (search_web_2), para que la búsqueda web y las reservas sigan funcionando. Una acción del lado del cliente conserva su nombre exacto, porque el controlador de tu página está registrado con él: no llames a una search_web, o el agente no podrá usar la búsqueda web mientras esté activada.
  • 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.

Ver como Markdown