Utilización del paso Hacer llamada de API en un bot de conversación

Atención: Zendesk ha cambiado el nombre de las capacidades relacionadas con los bots. El Answer Bot ahora se llama bots de Zendesk, el generador de flujos ahora se llama generador de bots y las Recomendaciones de artículos ahora se llaman respuestas automáticas. Algunas funciones más antiguas todavía usan la terminología anterior, que se refleja en la documentación. Si desea más información sobre este cambio, consulte este anuncio.

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
• Agregar detalles de la API
• Guardar variables de la respuesta de la 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 bot de conversación 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 bots.
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://. 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.
4. 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.
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.

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.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 no es válida o está vacía, el bot la omite durante la conversación.

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

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 ocho variables en un paso Hacer llamada de API.

Nota: Solo los primeros 280 caracteres del valor de una variable aparecen en la respuesta que se muestra en la conversación de mensajería.

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.

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.

Si la API devuelve un código de respuesta de 400, 500, o 200 con datos a los que les faltan cualquiera de las variables, el bot seguirá por la rama de fallas.

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 Contrato de servicios principales). Zendesk no opera ni controla los Servicios no proporcionados por Zendesk que se activen a raíz del uso de la función de extensiones del generador de bots, ni tampoco es responsable de las obligaciones de cumplimiento legales y reglamentarias que usted tenga ni de los servicios no proporcionados por Zendesk.