Conectores API para datos en vivo del Chatbot
Conectores API
Los Conectores API permiten que tu chatbot llame a API REST externas durante una conversación para obtener datos en tiempo real. Utilízalos para buscar pedidos, consultar inventario, verificar cuentas o extraer información de cualquier servicio que exponga una API. El chatbot recopila los datos necesarios del visitante, llama a tu API, valida la respuesta y presenta el resultado de forma conversacional.
Añadir un conector API
Abre tu asistente en el Panel, despliega Ajustes avanzados debajo de las pestañas principales, selecciona Conectores API y haz clic en Añadir Conector API. Los conectores API no son un Canal ni una Función. Puedes comenzar desde una plantilla prediseñada o crear un conector personalizado desde cero.
Campos de configuración
Configuración básica
| Campo | Descripción | Obligatorio |
|---|---|---|
| Nombre | Un nombre descriptivo para este conector (por ejemplo, "Búsqueda de pedidos", "Consulta de inventario"). | Sí |
| URL | La URL del endpoint API (por ejemplo, https://api.example.com/orders). | Sí |
| Método | Método HTTP: GET, POST, PUT, PATCH o DELETE. | Sí (predeterminado: GET) |
| Headers (JSON) | Encabezados HTTP opcionales en formato JSON (por ejemplo, {"Authorization": "Bearer abc123", "Content-Type": "application/json"}). Debe ser un JSON válido. | No |
| Habilitado | Indica si este conector está activo. | Sí (predeterminado: Activado) |
Cuerpo de la Solicitud (solo POST/PUT/PATCH)
| Campo | Descripción |
|---|---|
| Tipo de Contenido del Cuerpo | Formato del cuerpo de la solicitud: JSON o Form Data. |
| Plantilla del Cuerpo de la Solicitud | Plantilla para el cuerpo de la solicitud. Utiliza marcadores de posición como {email}, {order_id} que correspondan a tus campos definidos. |
Ejemplo de plantilla del cuerpo:
{
"email": "{email}",
"order_id": "{order_id}"
}
Campos
Los campos definen qué información necesita recopilar el chatbot del visitante antes de llamar a la API. Cada campo tiene:
| Propiedad | Descripción | Obligatorio |
|---|---|---|
| Nombre del Campo | El identificador del campo (por ejemplo, order_id, email). Se utiliza como marcador de posición en el cuerpo de la solicitud. | Sí |
| Tipo | Tipo de datos: string, number, email o boolean. | Sí (predeterminado: string) |
| Descripción (para la IA) | Explica a la IA para qué sirve este campo y cómo solicitárselo al visitante. | No |
| Obligatorio | Indica si el visitante debe proporcionar este campo antes de que se llame a la API. | No |
Ejemplo de campos:
| Nombre | Tipo | Descripción | Obligatorio |
|---|---|---|---|
order_id | string | El número de pedido del cliente, normalmente empieza por ORD- | Sí |
email | El correo electrónico utilizado al realizar el pedido | Sí |
Reglas de Validación de Respuesta
Las reglas de validación verifican que la respuesta de la API coincida con los datos introducidos por el visitante. Esto evita devolver información a la persona equivocada o sobre un pedido incorrecto.
Cada regla tiene:
| Propiedad | Descripción |
|---|---|
| Campo de Entrada | Qué campo proporcionado por el visitante se debe validar (a partir de tus campos definidos). |
| Ruta de Respuesta | Ruta al valor en la respuesta de la API (por ejemplo, billing.email, data.order.status). Utiliza la notación por puntos para objetos anidados. |
| Comparación | Cómo comparar: equals, equals (ignore case), contains o not empty. |
| Mensaje de Error | Mensaje que se muestra al visitante cuando falla la validación (por ejemplo, "El correo electrónico no coincide con nuestros registros"). |
Ejemplo de validación:
| Campo de Entrada | Ruta de Respuesta | Comparación | Mensaje de Error |
|---|---|---|---|
| billing.email | equals (ignore case) | El correo electrónico no coincide con el pedido. Por favor, compruébalo e inténtalo de nuevo. |
Prompt
Instrucciones para la IA sobre cuándo y cómo utilizar este conector. Esto es fundamental para que el chatbot sepa cuándo activar la llamada a la API.
Ejemplo de prompt:
Use this connector when a customer asks about their order status, shipping
information, or delivery date. Ask for their order ID and email address before
making the API call. Present the order status, shipping method, and estimated
delivery date in a friendly format.
Cómo funciona
- El visitante hace una pregunta que coincide con el prompt del conector (por ejemplo, "¿Dónde está mi pedido?")
- El chatbot solicita los campos obligatorios (por ejemplo, ID del pedido, correo electrónico)
- El visitante proporciona la información
- El chatbot llama a la API con los datos recopilados
- Se comprueban las reglas de validación con respecto a la respuesta
- Si la validación es correcta, el chatbot presenta los datos en un formato conversacional
Encadenar múltiples Conectores API
Puedes combinar múltiples conectores API para gestionar flujos de trabajo complejos. La IA los encadena automáticamente cuando es necesario.
Ejemplo: Autenticación y recuperación de datos
- Conector 1, "Autenticar Cliente": llama a un endpoint de inicio de sesión con el correo electrónico y la contraseña del visitante, y recibe un token de autenticación en la respuesta.
- Conector 2, "Obtener Detalles del Pedido": utiliza el token de la primera solicitud para llamar a un endpoint de API protegido y recuperar los datos del pedido.
La IA gestiona esto a la perfección: reconoce que el segundo conector requiere datos del primero, ejecuta las llamadas en el orden correcto y presenta el resultado final al visitante, todo dentro del mismo flujo de conversación.
Para configurarlo, define cada conector de forma independiente con su propio endpoint, campos y prompt. En el prompt del segundo conector, describe que depende de los datos del primero (por ejemplo, "Utiliza el token de autenticación del conector Autenticar Cliente para llamar a este endpoint"). La IA coordinará la secuencia automáticamente.
Prácticas recomendadas
- Escribe prompts claros: el prompt es el campo más importante, ya que determina cuándo se activa el conector
- Añade reglas de validación: valida siempre los datos confidenciales para evitar filtraciones de información
- Utiliza descripciones de campo claras: ayuda a la IA a hacer las preguntas correctas de forma natural
- Realiza pruebas con respuestas de API reales: asegúrate de que la ruta de respuesta coincida con la estructura real de tu API
- Gestiona los errores adecuadamente: define mensajes de error claros para los fallos de validación
- Utiliza encabezados de autenticación: protege siempre tus endpoints de API con la autenticación adecuada