El paso Hacer llamada de API permite configurar una llamada de API a otro sistema, como un sistema CRM o ERP interno, o enviar los detalles de la conversación a un extremo externo, como Amazon Event Bridge o Google Analytics.
En este artículo se describen los procedimientos para incluir y configurar el paso en un bot de conversación.
Si desea información general sobre el paso Hacer llamada de API y sus reglas de configuración, consulte Comprender los tipos de pasos del bot: Hacer llamada de API.
Este artículo contiene las siguientes secciones:
Agregar un paso Hacer llamada de API al bot
Para agregar el paso Hacer llamada de API al bot hay que realizar varias tareas específicas.
Para agregar un paso Hacer llamada de API
- En el Centro de administración, haga clic en
Canales en la barra lateral y luego seleccione Agentes IA y automatización > Agentes IA. - Haga clic en Administrar bots de conversación.
- Haga clic en el nombre del bot que desea editar.
- Haga clic en la pestaña Respuestas y luego cree una respuesta nueva o abra una respuesta existente.
- En el generador de bots, haga clic en el icono Agregar paso donde desea insertar el paso, ya sea al final de una rama o entre dos pasos existentes.
- En el panel Configuración, haga clic en Hacer llamada de API.
- Ingrese información descriptiva para el paso.
- Nombre: un nombre para la llamada que ayude al equipo a identificarla.
- Descripción (opcional): una descripción corta de la acción realizada por la llamada.
Los clientes no podrán ver esta información.
- Continúe con el procedimiento que se describe en Agregar detalles de la API.
Agregar detalles de la API
Utilice la sección Detalles de la API para configurar la llamada HTTP que desea hacer, incluyendo el método de solicitud HTTP y la ubicación del recurso externo, y agregando encabezados si es necesario. Los pasos siguientes son una continuación del procedimiento que se describe en la sección anterior.
Para agregar los detalles de la API
- En el panel Configuración, haga clic en Detalles de la API.
- Seleccione un Método de solicitud.
- GET obtiene un recurso externo del servicio de API. Este es el método más usado.
- POST envía datos para crear un recurso en un sistema externo. Si el recurso ya existe, los datos enviados modifican el recurso.
- PUT envía datos para actualizar un recurso.
- PATCH envía datos para actualizar un recurso en un sitio externo. Se usa para aplicar modificaciones parciales al recurso.
- DELETE elimina el recurso en la ubicación externa.
- Ingrese un URL de extremo.
El URL de extremo es la ubicación del recurso externo con el cual desea conectarse. El URL admite el protocolo
https://. Las variables se pueden agregar a la ruta de URL o a los valores de la cadena de consulta. Si desea más información, consulte Pasar variables en una llamada de API. - Opcionalmente, seleccione una conexión para autenticar la llamada de API.
Nota: Primero debe crear una conexión para poder usarla en el paso Hacer llamada de API.
- De ser necesario, ingrese la clave y el valor para un encabezado opcional. Importante: No use encabezados para autenticar. En lugar de ello, use conexiones de API.
Los pasos Hacer llamada de API que incluyan encabezados relacionados con una autenticación, como
authorizationox-api-key, fallarán de inmediato. Si un paso Hacer llamada de API falla, la conversación sigue la rama Error de llamada de API. - Para probar la llamada de API, haga clic en Hacer llamada de API.
Si se agregan variables al URL o encabezado del paso, se pueden incluir datos de prueba opcionales en el servicio externo para comprobar si la llamada de API está funcionando como se espera. Tenga en cuenta que esto hará una solicitud de HTTP al URL de extremo configurado.
Pasar variables en una llamada de API
Si se ingresa un URL de extremo para una llamada de API, se pueden incluir variables en la ruta del URL o los valores de la cadena de consulta. De esta manera se pueden pasar datos de la conversación al sistema externo.
Por ejemplo, un bot de mensajería puede solicitarle al cliente que proporcione el número de su pedido mediante un paso Solicitar detalles y luego usar el paso Hacer llamada de API para averiguar el estado de envío de ese pedido de la tienda en línea.
Las variables no se pueden usar en el dominio ni el subdominio de un URL de extremo. La siguiente tabla presenta ejemplos de valores de URL de extremo válidos y no válidos.
| URL de extremo válido | URL de extremo no válido |
|---|---|
https://myshopify.com/admin/api/orders/order_number.jsonRecuperar un pedido especificando la ID del pedido de Shopify. 
|
Las variables no se pueden agregar al dominio/subdominio |
|
Recuperar una ubicación en función de búsquedas de palabras clave de la API de lugares de Google. |
Las variables no se pueden agregar a la clave de la cadena de consulta |
Si una variable no es válida o está vacía, el bot la omite durante la conversación.
Guardar variables de la respuesta de la API
Después de configurar los detalles y comprobar la llamada de API, se pueden guardar los valores de la respuesta JSON de la llamada de API como variables. Se pueden guardar hasta 12 variables en un paso Hacer llamada de API. Solo se guardan los primeros 280 caracteres del valor de una variable.
Para crear una variable a partir de los datos de Respuesta
- En el panel Configuración, haga clic en Hacer llamada de API.
- Amplíe el acordeón e identifique los datos del sistema externo que desea convertir en una variable.
Sugerencia: Cambie a la pestaña Cuerpo de respuesta para ver la respuesta sin procesar devuelta por el sistema externo.
- Haga clic en Guardar.
- Dele un nombre a la nueva variable.
Los nombres de variables solo pueden incluir letras minúsculas, números y caracteres de subrayado.
Pasar variables de matriz en una llamada de API
{
"info": {
"count": 50,
"pages": 2,
"next": "https://mycompany.com/api/orders?page=2",
"prev": null
},
"results": [
{
"id": 1052,
"name": "Alexander Cummings",
“address”: “123 MyStreet”,
"Item": "belt",
"price": "15.00",
"image": "https://mycompany.com/api/orders/avatar/1.jpeg",
…
id, name, address, item, price e image. Estos datos normalmente se pasan a un carrusel; sin embargo, el carrusel solo puede mostrar hasta 10 elementos.
lastname y firstname se pueden guardar como variables de matriz separadas.
"name":
{
"lastname": "Cummings”,
"firstname": “Alexander"
},
No es posible editar la matriz o los valores de matriz dentro de la configuración del carrusel en el Centro de administración. Si tiene que cambiar los datos, debe borrar la matriz en el Centro de administración y crear una nueva.
{{customer.order}} está vacío. Para la tarjeta 1, la tarjeta se renderizará con un título parcial "Order number". Para la tarjeta 2, el título resultante estará vacío, de modo que la tarjeta 2 no se renderizará.
Card 1
Title: Order number {{customer.order}}
Description: Here's your order {{product.description}}
Card 2
Title: {{customer.order}}
Description: Here's your order {{product.description}}
Ejemplo
{
"info": {
"count": 5,
"pages": 1
},
"results": [
{
"createdAt": "July 10, 2023",
"name": "Connie Stokes",
"Shippingaddress": "123 Street, City, State",
"order": {
"Status": "Ordered",
"Image": "https://images.pexels.com/photos/1484808/pexels-photo-1484808.jpeg"
},
"Quantity": 1,
"Price": 45,
"Item": "Shirt",
"id": "1"
},
… En este ejemplo, se usa Hacer llamada de API para crear la variable de matriz y luego se utiliza un carrusel dinámico para mostrar los resultados a un usuario final.
Para crear una matriz
- En el panel Configuración, haga clic en Hacer llamada de API.
- Ingrese orders para el nombre.
- En el panel Configuración, haga clic en Detalles de la API.
- Haga clic en el menú desplegable Método de solicitud y seleccione GET.
- Ingrese el URL para el URL de extremo.
- Para Autenticación, seleccione el método de autenticación.
Si desea más información, consulte Creación de conexiones de API para el generador de bots.
- Haga clic en Hacer llamada de API
- Haga clic en Guardar junto a “results”.
- En el menú desplegable Valor, seleccione Order y luego Image.
Utilice el nombre predeterminado de la variable (image).
- Haga clic en Agregar elemento y repita el paso anterior para crear elementos para Order Status e Item.
Puede agregar hasta 12 elementos (o pares clave-valor).
- Haga clic en Guardar.
- En el generador de bots, haga clic en Agregar paso bajo La llamada a la API se realizó correctamente y seleccione Agregar carrusel.
- En el panel Configuración, haga clic en Convertir a mensaje dinámico.
- En el menú desplegable Matriz, haga clic en results. Esta es la matriz que se creó anteriormente.
- Para el título, haga clic en el signo de más y seleccione results.item.
Se pueden ingresar hasta 128 caracteres para el título y la descripción.
- Para Vínculo del botón, haga clic en el signo de más y seleccione results.image.
- Para Texto del botón, haga clic en el signo de más y seleccione results.status.
- Para Vínculo de imagen, haga clic en el signo de más y seleccione results.image.
- Haga clic en Terminado.
Este es un ejemplo de un carrusel dinámico.
Acerca de las ramas del paso
El paso Hacer llamada de API es un paso de rama. Si se agrega este paso, las respuestas del bot se dividen según si la API se ejecutó correctamente.
- La API devuelve un código de respuesta 400 o 500.
- La API devuelve un código de respuesta 200 cuando una de las variables guardadas falta o tiene el valor
null.
En todos los demás casos, el bot bajará en la rama de éxito.