Bloque de API, llama a APIs externas desde el flujo de tu chatbot

Visión general

El bloque de API permite que tu chatbot llame a cualquier API REST externa a mitad de la conversación, capture la respuesta y enrute el flujo según el éxito o el fallo. Úsalo para buscar pedidos en tu base de datos, verificar OTP, obtener el estado de un envío, consultar saldos de cuenta o integrar cualquier sistema que exponga un endpoint HTTP.

Cuando el bot llega a un bloque de API, envía la solicitud HTTP configurada, espera la respuesta, extrae campos del cuerpo JSON o XML hacia variables y luego sigue la rama de éxito (HTTP 2xx/3xx) o la rama de fallo (HTTP 4xx/5xx). Los bloques siguientes del flujo pueden usar las variables extraídas en mensajes, condiciones o llamadas a la API posteriores.

Dónde encontrarlo

1. Abre tu chatbot en Studio
2. Arrastra el bloque API desde la barra lateral izquierda al lienzo
3. Conéctalo desde cualquier bloque anterior
4. Haz doble clic en el bloque para configurarlo

El bloque de API tiene dos conexiones de salida: Éxito (superior/predeterminada) para respuestas 2xx y 3xx, y Fallo (secundaria) para respuestas 4xx y 5xx.

Configuración

Paso 1: Establece la URL y el método de la solicitud

Campo	Descripción
URL	El endpoint completo; por ejemplo, https://api.example.com/orders/{order_id}
Método	Verbo HTTP: GET, POST, PUT, PATCH o DELETE

Puedes insertar cualquier variable capturada antes en el flujo usando la sintaxis {variable_name} (llaves simples). Las variables se resuelven en tiempo de ejecución antes de enviar la solicitud.

Paso 2: Añade parámetros de consulta (opcional)

Para las solicitudes GET, usa Parámetros de consulta para añadir pares clave-valor a la URL. Cada fila admite una clave y un valor. La sustitución de variables funciona en ambos campos.

Key: customer_email       Value: {email}
Key: include_archived     Value: false

Paso 3: Configura los encabezados

Añade encabezados HTTP personalizados en la sección Encabezados. Cada fila admite una clave y un valor.

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

El Content-Type se detecta automáticamente cuando eliges un formato de cuerpo, pero puedes sobrescribirlo.

Paso 4: Añade autenticación

El bloque de API admite tres modos de autenticación. Elige el que coincida con tu API de destino.

Tipo de autenticación	Campos	Cómo se envía
Autenticación básica	Usuario, contraseña	Se envía como Authorization: Basic <base64>
Token Bearer	Token Bearer	Se envía como Authorization: Bearer <token>
Encabezado personalizado	Nombre del encabezado, valor del encabezado	Se envía como <Name>: <Value> (para claves de API, esquemas personalizados)

Nota: Para las APIs que usan x-api-key o similar, elige Encabezado personalizado y establece el nombre en x-api-key y el valor en tu clave. También puedes guardar la clave en una variable y referenciarla como {api_key}.

Paso 5: Construye el cuerpo de la solicitud

Para las solicitudes POST, PUT y PATCH, configura el cuerpo en la sección Cuerpo. Elige el formato:

Formato	Úsalo cuando
JSON	La mayoría de las APIs REST modernas
XML	Endpoints SOAP o XML heredados
Ninguno	No se necesita cuerpo (habitual en GET y DELETE)

Escribe el JSON o XML sin procesar en el editor del cuerpo. Las variables se pueden insertar en línea:

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

Paso 6: Asigna la respuesta a variables

En Guardar respuesta en variables, define cómo extraer campos de la respuesta JSON hacia variables del flujo.

Ruta JSON	Nombre de la variable
result.user.name	user_name
data.orders[0].status	order_status
items[*].id	item_ids

Sintaxis de ruta admitida:

• Notación con puntos para objetos anidados: result.user.email
• Índice de array: items[0].name
• Extracción con comodín en array: items[*].id devuelve todos los ID como un array
• Campo raíz: status o message

Los valores extraídos están disponibles en todos los bloques siguientes como {variable_name}.

Paso 7: Envía y guarda

Haz clic en Enviar en el modal del bloque y luego guarda el flujo con Guardar cambios en la barra superior.

Cómo se gestiona la respuesta

Ruta de éxito (HTTP 2xx / 3xx)

1. Se completan las variables de Guardar respuesta en variables
2. El flujo sigue la conexión de salida de Éxito

Ruta de fallo (HTTP 4xx / 5xx)

1. Las variables de respuesta pueden completarse o no, según el cuerpo del error
2. El flujo sigue la conexión de salida de Fallo
3. Usa esta rama para enviar un mensaje de error amable o para reintentar

Tiempo de espera

Las solicitudes expiran tras 30 segundos. Si tu API es lenta, considera dividir el trabajo en dos pasos o usar un patrón asíncrono basado en webhooks.

Pruebas en el Playground de API

Cada llamada del bloque de API se registra y está disponible en el Playground de API dentro de Studio. Para cada ejecución de prueba puedes ver:

• La URL, el método y los encabezados completamente resueltos
• El cuerpo de la solicitud que se envió
• El código de estado HTTP recibido
• El cuerpo completo de la respuesta
• Las variables que se extrajeron

Usa el playground para depurar las variables de plantilla, la autenticación y las asignaciones de rutas JSON antes de publicar el flujo.

Buenas prácticas

• Guarda los secretos en variables, no en la configuración del bloque. Captura las claves de API desde ajustes específicos del entorno y pásalas mediante variables para que el mismo flujo funcione en staging y producción
• Configura siempre la rama de fallo. Nunca des por hecho que la llamada a la API tiene éxito. Envía un mensaje alternativo como "No pudimos recuperar tu pedido en este momento. Inténtalo de nuevo más tarde."
• Mantén los cuerpos de solicitud pequeños. No envíes historiales de chat completos ni cargas grandes a menos que la API los necesite
• Valida los campos de la respuesta antes de usarlos. Si order_status puede faltar, añade un bloque de condición después de la llamada a la API para comprobar {order_status} antes de usarlo en un mensaje
• Usa nombres de variable descriptivos. user_email es mejor que val1 porque es más fácil de depurar en el Playground y en el registro de la conversación
• Establece el Content-Type de forma explícita al enviar JSON, para que las APIs estrictas acepten la solicitud

Casos de uso comunes

Búsqueda de pedidos

El cliente proporciona un ID de pedido y el bot obtiene el estado desde tu backend de comercio electrónico.

• Método: GET
• URL: https://api.myshop.com/orders/{order_id}
• Autenticación: token Bearer
• Asignación de respuesta: data.status a order_status, data.tracking_url a tracking_url

Verificación de OTP

El bot recopila un código de 6 dígitos, llama a tu endpoint de verificación y se ramifica según el resultado.

• Método: POST
• URL: https://api.myapp.com/verify-otp/
• Cuerpo: {"phone": "{phone}", "code": "{otp_code}"}
• Asignación de respuesta: verified a otp_verified
• Usa un bloque de condición a continuación: si {otp_verified} == true continúa, de lo contrario vuelve a preguntar

Sincronización de contactos con el CRM

Envía los datos de contacto recopilados a tu CRM cuando el usuario completa la calificación.

• Método: POST
• URL: https://api.crm.com/v1/contacts/
• Autenticación: encabezado personalizado (x-api-key: {crm_key})
• Cuerpo: {"name": "{name}", "email": "{email}", "source": "chatbot"}

Solución de problemas

La solicitud falla con 401 No autorizado

1. Comprueba que el tipo de autenticación coincide con lo que espera la API
2. Para los tokens Bearer, no incluyas la palabra Bearer en el campo del token. El bloque la añade automáticamente
3. Para la autenticación con encabezado personalizado, verifica que el nombre del encabezado coincide exactamente con la documentación de la API (sensible a mayúsculas en algunas APIs)
4. Inspecciona la solicitud en el Playground de API para confirmar que el encabezado se está enviando

Las variables no se completan a partir de la respuesta

1. Abre el Playground de API e inspecciona el cuerpo real de la respuesta
2. Confirma que la ruta JSON coincide con la estructura de la respuesta. Las rutas son sensibles a mayúsculas
3. Para arrays, usa items[0].field para un solo valor o items[*].field para todos los valores
4. Si la respuesta es XML, asegúrate de configurar correctamente el formato del cuerpo. Las rutas JSON también funcionan sobre el XML analizado

El flujo sigue la rama de fallo aunque la API funcione

1. Comprueba el código de estado HTTP en el Playground de API. Algunas APIs devuelven 201 (Created) en POST, que sigue siendo éxito
2. Si la API devuelve 200 pero con un error en el cuerpo, usa un bloque de condición después de la rama de éxito para inspeccionar el campo de respuesta

La solicitud expira

1. El tiempo de espera es fijo en 30 segundos. Si tu API tarda regularmente más, puede que no sea una buena opción para un chat en tiempo real
2. Considera mover el trabajo lento a una tarea en segundo plano y sondear el resultado, o usa un webhook para recibir aviso cuando esté listo

Las variables de plantilla aparecen como {variable} sin procesar en la solicitud

1. Confirma que la variable fue establecida por un bloque anterior en el flujo
2. Revisa la ortografía del nombre de la variable (sensible a mayúsculas)
3. Usa el registro de la conversación para inspeccionar qué variables están realmente completadas en ese punto

Próximos pasos

• Bloque de webhook: recibe llamadas HTTP entrantes para activar o reanudar un flujo
• Bloque de fin de conversación: finaliza conversaciones con un botón de reinicio
• Visión general de Studio: explora todos los tipos de bloque y las funciones del constructor de flujos