Las integraciones personalizadas de API permiten que tu chatbot consulte información en tiempo real desde tu ERP, almacén, CRM u otro servicio. También pueden realizar cambios, como crear una cita. Una integración almacena la URL base; cada operación define una solicitud ejecutable. Luego, vinculas las operaciones seleccionadas a un chatbot como acciones de IA (AI actions).
Antes de empezar
Comprueba que tu cuenta incluya integraciones personalizadas de API. Necesitas la URL del endpoint, el método HTTP, los nombres y tipos de parámetros, los requisitos de autenticación y una respuesta de ejemplo. El endpoint debe ser accesible desde los servidores de ChatLab; localhost en tu ordenador no es un endpoint de producción.
Utiliza HTTPS y un servicio de prueba o registros de prueba para la configuración. Una solicitud de prueba llama realmente al endpoint, por lo que un POST, PATCH o DELETE puede modificar datos externos. Haz que las operaciones sean seguras de repetir siempre que sea posible.
1. Crear una integración
- Abre Custom Integrations (Integraciones personalizadas) en la navegación principal.
- Haz clic en + Define API Integration (+ Definir integración de API).
- Introduce el API name (Nombre de la API) y la API Base URL (URL base de la API), por ejemplo
https://api.example.com. - Haz clic en Create API Integration (Crear integración de API).
- En su entrada de la lista, haz clic en View (Ver) y luego en + Define API Operation (+ Definir operación de API).
2. Definir la operación
Asigna a la operación una etiqueta reconocible y un nombre legible por máquina en Operation name (Nombre de la operación), como getProductDetails. Usa únicamente letras y números para el nombre de la operación, sin espacios ni guiones bajos. Describe qué hace la operación y cuándo debe usarla el chatbot.
Introduce el URI relativo, por ejemplo /v1/products/@productId@. La URL base y el URI forman la dirección de la solicitud.
Algunas capturas de pantalla existentes muestran nombres de ejemplo anteriores o marcadores de posición con llaves. Sigue la sintaxis actual indicada a continuación: nombres de operación como getProductDetails y marcadores de posición de parámetros rodeados por @.
Parámetros de ruta y de consulta
Haz clic en Add path variable (Añadir variable de ruta) para definir productId. Configura su tipo de datos y la fuente del valor; luego incluye @productId@ en el URI. Las variables de ruta son obligatorias, y cada variable de ruta definida debe aparecer en el URI antes de que puedas guardar o probar.
Usa Add query parameter (Añadir parámetro de consulta) para parámetros como limit o language que van después del signo de interrogación de la URL. Introduce el nombre que espera tu API, su tipo, descripción y fuente del valor.
Las fuentes de valor disponibles incluyen:
- Provided by user or chatbot (Proporcionado por el usuario o chatbot): el modelo proporciona un valor a partir de la conversación. Explica el formato esperado y marca adecuadamente los valores obligatorios.
- Constant (Constante): un valor configurado en la operación, como un identificador de cuenta fijo o una credencial de API restringida.
- Random value (Valor aleatorio): un valor generado automáticamente.
- Client context (Contexto del cliente): un valor transmitido por el sitio web anfitrión, cuando esté disponible para tu cuenta. Consulta Chat API.
Los tipos escalares incluyen string, integer, double y boolean. Los parámetros del cuerpo también admiten arrays de string e integer.
3. Configurar el método y el cuerpo
Elige GET, POST, PUT, PATCH o DELETE según corresponda a tu endpoint. Para métodos distintos de GET, el editor ofrece contenido de solicitud en formato raw (sin procesar) o form-data.
Para un cuerpo JSON en formato raw, define los parámetros del cuerpo e inserta sus marcadores de posición @name@ en la plantilla. Añade el encabezado Content-Type correspondiente que requiera tu endpoint. Por ejemplo, con parámetros de cadena name y de matriz de cadenas tags:
{
"name": "@name@",
"tags": @tags@
}
Esto es una plantilla, no un JSON literal hasta que se realiza la sustitución. Los marcadores de posición de matrices no deben ir entre comillas. Cada parámetro del cuerpo definido debe utilizarse en la plantilla cuando se aplique el editor de cuerpo en formato raw. Revisa la solicitud procesada durante las pruebas, incluido el texto que contenga comillas o caracteres especiales.
4. Añadir encabezados de autenticación
Usa Add header (Añadir encabezado) para definir los encabezados que espera la API. Para un token de tipo bearer, usa el nombre de encabezado Authorization, la fuente del valor Constant (Constante) y el valor Bearer YOUR_RESTRICTED_TOKEN.
Mantén los secretos fuera de los prompts y las URL. Evita operaciones que devuelvan tokens de inicio de sesión al modelo y dependan de instrucciones para ocultarlos. Da prioridad a un endpoint de integración del lado del servidor que gestione su propia autenticación y exponga únicamente la operación permitida.
5. Guardar y probar la solicitud
- Haz clic en Save changes (Guardar cambios) en el editor de operaciones. A diferencia de los ajustes normales del chatbot (Settings), este editor incluye un botón explícito para guardar.
- Haz clic en Test API Operation (Probar operación de API). Está deshabilitado mientras haya cambios sin guardar.
- Introduce valores representativos para los parámetros. Para las entradas de prueba de tipo array, usa valores separados por comas.
- Ejecuta la prueba únicamente con datos que tengas autorización para leer o modificar.
- Revisa el código de estado, el cuerpo de la respuesta, la URL de la solicitud, los encabezados, el cuerpo y cualquier advertencia que aparezca en los resultados.
- Corrige los errores, guarda y repite el proceso según sea necesario.
No compartas resultados de prueba que contengan credenciales. Devuelve datos específicos y paginados siempre que sea posible: las respuestas extensas pueden truncarse antes de llegar al modelo.
6. Asociar la operación a un chatbot
Abre tu chatbot y ve a Settings > Actions (Ajustes > Acciones). Usa el botón más para añadir una acción, busca tu operación dentro de las API personalizadas y asóciala o actívala. Crear una integración a nivel de cuenta no hace que todas las operaciones estén disponibles automáticamente para cada chatbot.
Revisa las instrucciones de la acción y las opciones de seguridad disponibles, y luego espera al estado de guardado. Consulta Acciones de IA para conocer el editor de acciones.
7. Explicar cuándo usarla
Abre Settings > Role & Behavior (Ajustes > Rol y comportamiento).
Si utilizas instrucciones de rol personalizadas, selecciona Custom Role Definition (Definición de rol personalizada) y añade una regla precisa, por ejemplo: "Cuando el visitante pregunte si un producto está en stock, llama a getProductDetails con su ID de producto. Informa sobre la disponibilidad obtenida. Si la consulta falla, explica que no se pudo comprobar la disponibilidad".
Conserva las demás instrucciones útiles del chatbot. Espera al estado de guardado y, a continuación, usa la vista previa de Overview (Resumen) para probar preguntas realistas, parámetros faltantes, errores y solicitudes no autorizadas. Las conversaciones de vista previa pueden ejecutar operaciones reales.
La invocación por parte de la IA no está garantizada ni se realiza necesariamente una sola vez. Haz pruebas con el modelo seleccionado para tu chatbot; no asumas que el nombre del modelo por sí solo garantiza el uso correcto de las herramientas.
Seguridad y solución de problemas
Tu endpoint debe autenticar las solicitudes y autorizar el acceso de cada usuario antes de devolver información confidencial o realizar cambios. Un ID de cliente proporcionado por el navegador, un correo electrónico, un número de pedido o un campo de contexto no constituyen una prueba de identidad suficiente. Si pasas un token por usuario mediante el contexto del cliente, tu servidor debe validarlo.
Devuelve únicamente los campos que el chatbot necesita, como el estado del pedido en lugar de un perfil de cliente completo. Las instrucciones del prompt pueden orientar la redacción, pero no garantizan que los datos confidenciales devueltos al modelo permanezcan ocultos.
Si la solicitud tiene éxito en el editor de pruebas pero falla en una conversación, comprueba la acción vinculada, si está habilitada, las instrucciones, los parámetros obligatorios y el contexto disponible. Si ambas fallan, revisa la URL, el método HTTP, la autenticación, el cuerpo renderizado y los registros de tu endpoint. Evita reintentar de forma repetida una operación de escritura hasta saber si la solicitud anterior tuvo éxito.