El elemento Solicitud de API en chatbots

La automatización del proceso de recuperación de datos se ha vuelto aún más fácil con las solicitudes de API. Puedes solicitar datos sobre la información que le interesa a tu usuario, crear un perfil de cliente o registrarte para un evento en sistemas externos. En respuesta, recibe información que puedes mostrar directamente en un mensaje al usuario o guardarla en una variable de chatbot.

Cómo enviar una solicitud de datos

El elemento Solicitud de API envía una solicitud a un servidor externo utilizando datos de tu chatbot. Agrega una URL de solicitud, encabezados y cuerpo, y luego decide cómo se debe procesar la respuesta.

Configura la solicitud

Arrastra el elemento Solicitud de API al área de trabajo y conéctalo al elemento después del cual deseas obtener información.

Selecciona el tipo de solicitud:

• Una solicitud GET suele utilizarse para obtener datos existentes;
• Una solicitud POST suele utilizarse para crear un nuevo objeto en el sistema y obtener información sobre él.

Ingresa la URL para enviar la solicitud. Puedes utilizar las variables personalizadas y globales de tu chatbot y modificarlas en la solicitud. Para seleccionar variables, haz clic en {} en la esquina superior derecha del campo de texto. Para encontrar una variable, en la parte superior del menú desplegable de variables, escribe el nombre de la variable en el campo de búsqueda Buscar por nombre.

Para agregar encabezados de solicitud, por ejemplo, para autorizar solicitudes, haz clic en Agregar encabezados. También puedes utilizar variables del bot en los encabezados de la solicitud.

Si utilizas una solicitud POST, en el campo requerido introduce el cuerpo de la solicitud en JSON con parámetros. También puedes modificar un cuerpo de solicitud.

Haz clic en Probar solicitud para verificar el envío de los datos. Además, esta prueba es útil para el reconocimiento de datos en las siguientes configuraciones.

Convierte los tipos de variables en el cuerpo de la solicitud

Cuando insertas una variable del chatbot en el cuerpo de una solicitud, tu chatbot la envuelve entre comillas de forma predeterminada y la envía como una cadena. Si la API de destino espera un tipo de datos diferente, como un número, un booleano o un objeto anidado, usa un modificador del cuerpo de la solicitud.

Un modificador del cuerpo de la solicitud es un indicador de tipo precedido por dos puntos que se coloca después del nombre de la variable, {{variable_name}}::type. Este modificador convierte los valores al tipo de datos especificado y elimina las comillas que los rodean de la salida JSON.

Puedes agregar los siguientes modificadores:

Por ejemplo, si utilizas el siguiente cuerpo de solicitud:

{
  "name": "{{full_name}}",
  "id": "{{crm_id}}::int",
  "stage_id": 2
}

Tu chatbot sustituirá las variables por sus valores y enviará:

{
  "name": "John",
  "id": 123,
  "stage_id": 2
}

Los chatbots envían el valor de id como un número. Las comillas que lo rodean se eliminan automáticamente.

Los modificadores del cuerpo de la solicitud difieren de los modificadores de variables. La notación con dos puntos solo se aplica al elemento Solicitud de API y se utiliza para convertir tipos de datos en las cargas útiles JSON.

Si introduces una variable en el cuerpo de la solicitud sin comillas a ambos lados, por ejemplo, "key": {{var}}, el editor del chatbot marca el cuerpo como JSON no válido.

Cómo usar los datos recibidos

Si la solicitud es exitosa, recibirás un cuerpo de respuesta y el usuario será dirigido hacia la rama Terminado.

Todas las respuestas de solicitud con el estado 2xx irán a la rama Terminado. Las respuestas de las solicitudes con otros estados irán a la rama Error y no podrás usar esos datos. Puedes leer más en: Cómo continuar un flujo en caso de un error de solicitud.

Puedes usar los datos recibidos en el siguiente elemento o guardarlos en una variable de chatbot para uso repetido.

La API puede regresar una respuesta de hasta 65 KB. El límite de tiempo del procesamiento de la solicitud es de 60 segundos.

Uso de datos guardándolos en una variable

Para guardar los datos como variables para uso futuro, el elemento Solicitud de API, ve a la pestaña Guardar valores y haz clic en Añadir en la configuración de asignación.

En el campo de respuesta, selecciona la clave cuyo valor de variable quieras utilizar.

Selecciona la variable donde quieres guardar tu valor. El campo de respuesta permite almacenar valores de hasta 1,024 caracteres.

Cuando hayas guardado el número requerido de variables, haz clic en Aplicar y procede a crear el siguiente elemento.

En este ejemplo, creamos un pedido, recibimos datos de nuestro CRM, los guardamos como variables e informamos al usuario para identificar rápidamente el servicio o producto que solicitó.

Como usuario, la interacción con tu chatbot se ve así:

Uso de datos como una expresión de ruta JSON

Si no necesitas escribir datos en variables, puedes usar la información recibida insertando una expresión de ruta JSON de la estructura.

Los datos que no estás escribiendo sólo se pueden usar una vez en el siguiente bloque de texto:

En el mensaje de texto, agrega el JSON Path {{$['somekey']['nestedkey']}}.

Para utilizar encabezados, cookies, códigos de estado y otros datos del sistema de una solicitud, haz referencia a ellos en el mensaje como {{$$['headers']}}, {{$$['cookies']}} o {{$$['data']}}.

Este enfoque es útil para integraciones que dependen de datos de autorización en cookies.

Como usuario, la interacción con tu chatbot se verá así:

Uso de datos para el envío de tarjetas

Con un plan de pago puedes generar y enviar tarjetas a partir de los datos recibidos en la respuesta a la solicitud. Para hacerlo, utiliza la pestaña Enviar mensajes, añade un enlace a tu API y rellena el formulario con los datos obtenidos del arreglo.

Read more: Cómo enviar tarjetas de mensajes en chatbots.

Cómo continuar un flujo en caso de un Error de solicitud

También puedes bifurcar tu escenario y, en caso de una solicitud de API fallida, continuar el flujo usando la rama Error. Por ejemplo, puedes notificar a los usuarios sobre un error, solicitar nuevamente los datos necesarios si no coinciden o invitar a un administrador.

También puedes pasar la respuesta de error del servidor. Esto te ayuda a mostrar un mensaje de error a los usuarios o registrar los detalles del error para la depuración. Para hacer referencia a un campo específico en la respuesta de error, utiliza una expresión JSON Path, como {{$['status_code']}}.

Última actualización: 08.01.2025