Utilización del paso Hacer llamada de API en el generador de flujos

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 flujo de bot.

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
• Agregar detalles de la API
• Guardar la respuesta de API como una variable
• Autenticar la llamada de API
• Acerca de las ramas del paso

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.

En los siguientes procedimientos se supone que ya se ha creado un flujo de bot y se está agregando este paso a ese bot.

Para agregar un paso Hacer llamada de API

1. Abra el bot en el generador de flujos.
2. Haga clic en el icono Agregar nuevo donde desea insertar el paso, ya sea al final de una rama o entre dos pasos existentes.
3. En el panel Configuración, haga clic en Hacer llamada de API.
4. Ingrese información descriptiva para el paso. Solo será visible para su equipo; los clientes no verán la información que se ingrese aquí:
   • 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.
5. Continúe con el procedimiento que se describe en Agregar detalles de la API, a continuación.

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

1. En el panel Configuración, haga clic en Detalles de la API.
2. Utilice el menú desplegable para seleccionar un Método de solicitud:
   • GET recupera datos de un servidor en el recurso externo. Este es el método más usado.
   • POST envía datos para crear o actualizar un recurso en un sistema externo. Si el recurso ya existe, los datos enviados modifican el recurso.
   • PUT envía datos para actualizar o crear un recurso. Si el recurso ya existe, los datos enviados reemplazan al 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.
3. 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://.
4. Opcionalmente, seleccione una conexión para autenticar la llamada de API.
   Nota: Antes de autenticar la llamada de API, debe crear una conexión.
5. 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 authorization o x-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.

6. 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.

Guardar la respuesta de API como una variable

Una variable es una manera de almacenar las respuestas de API. Las variables se pueden usar con distintas finalidades:

• Personalizar el mensaje del bot para los clientes. Por ejemplo, puede guardar el nombre de un cliente como una variable y hacer referencia a él en el mensaje del bot. Puede agregar variables en cualquier lugar del flujo después del paso Hacer llamada de API en el cual se creó la variable, en pasos que incluyen un mensaje configurable como los que siguen.
  • Enviar mensaje
  • Presentar opciones
  • Mostrar artículos del centro de ayuda
  • Transferir a agente

• Pasar datos de la llamada a un sistema externo. Por ejemplo, puede solicitarle a un cliente que proporcione un número de pedido y luego hacer una llamada de API al sistema de comercio electrónico para averiguar el estado de envío de ese pedido en particular. Si se usan variables en el paso Hacer llamada de API, hay que tener en cuenta ciertas restricciones.

  En el campo URL de extremo, las variables se pueden agregar solo a la ruta de URL o a los valores de la cadena de consulta. Las variables no se pueden usar en la parte del dominio o subdominio del URL. La siguiente tabla muestra ejemplos de lo que se puede hacer y lo que no se puede hacer con las variables:

  Configuración válida	Configuración no válida
  https://myshopify.com/admin/api/orders/order_number.json Recuperar un pedido especificando la ID del pedido de Shopify.	https://domain.com/api/search?input=value Las variables no se pueden agregar al dominio/subdominio
  https://maps.googleapis.com/maps/api/place?input=city_name Recuperar una ubicación en función de búsquedas de palabras clave de la API de lugares de Google.	https://example.com/api/search?key=value Las variables no se pueden agregar a la clave de la cadena de consulta

Si una variable se vuelve no válida (si se cambia el esquema de la API, por ejemplo), el bot omitirá la variable cuando se muestre al usuario final. Se pueden crear hasta ocho variables en el paso Hacer llamada de API.

Nota: El valor de las variables no se traduce automáticamente. Tenga esto es cuenta si utiliza la traducción automática para las conversaciones de mensajería.

Después de configurar los detalles de la API y probar la llamada de API, puede usar los datos de Respuesta devueltos para crear las variables. Los pasos siguientes son una continuación del procedimiento que se describe en la sección anterior.

Para crear una variable a partir de los datos de Respuesta

1. En el panel Configuración, haga clic en Hacer llamada de API.
2. 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.
3. Haga clic en Guardar.
4. Dele un nombre a la nueva variable. Los nombres de variables solo pueden incluir letras minúsculas, números y caracteres de subrayado.

Autenticar la llamada de API

En el paso Hacer llamada de API, se puede usar una conexión para autenticar las llamadas de API al servicio o sistema externo.

Para ello, primero se debe crear la conexión en el Centro de administración. Una conexión permite guardar y pasar credenciales de forma segura para el servicio. Consulte Creación de conexiones en el Centro de administración si desea obtener más información e instrucciones detalladas.

Si tiene problemas al tratar de agregar la conexión, consulte el Registro de auditoría en el Centro de administración para obtener más información.

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.

Cuando se ejecuta el bot, 200 códigos de respuesta harán que el bot se desplace por la rama que se ejecutó correctamente. Todos los 400 o 500 códigos de respuesta harán que el bot se desplace por la rama que falló. Si la API devolvió 200 con una respuesta vacía, las variables que se guarden de este paso se omitirán durante la ejecución.

Atención: Si utiliza el paso Hacer llamada de API, acepta que el sistema externo con el cual se conecta es un servicio no proporcionado por Zendesk (como se describe en el Acuerdo de Suscripción General). Zendesk no opera ni controla los Servicios no proporcionados por Zendesk que se activen a raíz del uso de la función Extensiones del generador de flujos, ni tampoco es responsable de las obligaciones de cumplimiento legales y reglamentarias que usted tenga ni de los servicios no proporcionados por Zendesk.