¿Qué plan tengo?
Suite Team, Growth, Professional, Enterprise o Enterprise Plus
Este artículo describe la funcionalidad disponible solo para los clientes que tenían un agente IA en borrador o publicado el 2 de febrero de 2025. Si desea información acerca de la funcionalidad equivalente en Agentes IA – Avanzado, consulte Integración de otras plataformas con Agentes IA – Avanzado.
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 agente IA para mensajería.

Si desea información general sobre el paso Hacer llamada de API y sus reglas de configuración, consulte Comprender los tipos de pasos de las respuestas de los agentes IA (heredado): Hacer llamada de API.

Este artículo contiene las siguientes secciones:

  • Agregar un paso Hacer llamada de API al agente IA
  • 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 agente IA

Para agregar el paso Hacer llamada de API al agente IA hay que realizar varias tareas específicas.

En los siguientes procedimientos se supone que ya se ha creado un agente IA para mensajería y se está agregando este paso a ese agente IA.
Nota: Si el sistema al que se llama no responde en 10 segundos, se agotará el tiempo máximo de inactividad de la llamada.

Para agregar un paso Hacer llamada de API

  1. En el Centro de administración, haga clic en IA en la barra lateral y luego seleccione Agentes IA > Agentes IA.
  2. Haga clic en Administrar agentes IA para mensajería.
  3. Haga clic en el nombre del agente IA que desea editar.
  4. Haga clic en la pestaña Respuestas y luego cree una respuesta nueva o abra una respuesta existente.
  5. 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.
  6. En el panel Configuración, haga clic en Hacer llamada de API.
  7. 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.

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

  1. En el panel Configuración, haga clic en Detalles de la API.
  2. 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.
  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 agente IA para 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 agente IA 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 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

  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.

Pasar variables de matriz en una llamada de API

Para pasar variables de matriz, se puede usar Hacer llamada de API y proporcionar un URL al sistema externo. El sistema externo debe tener una terminal de API. Una terminal de API es un URL donde la API recibe solicitudes y envía respuestas, lo que permite que dos sistemas interactúen. Las respuestas se renderizan en formato JavaScript Object Notation (JSON), como se muestra en el siguiente ejemplo.
{               
    "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",
	…
    
Solo los primeros elementos de la variable de matriz se muestran en el Centro de administración para poder visualizar qué datos se devuelven. Por ejemplo, en la salida JSON de arriba, se muestran 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.
Nota: Solo los primeros 280 caracteres de un valor de propiedad aparecen en la respuesta.
Las matrices JSON anidadas también se pueden guardar como variables de matriz. Por ejemplo, dada la siguiente salida de JSON, 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.

Si la variable que se devuelve es null, el elemento no se muestra en el carrusel. Por ejemplo, en el siguiente caso, supongamos que el valor de la variable {{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

En este ejemplo, se crea una variable de matriz usando un extremo de API que devuelve una matriz de pedidos. La matriz de pedidos se especifica con una propiedad "results" en el siguiente fragmento de la respuesta de API.

     {
  "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

  1. En el panel Configuración, haga clic en Hacer llamada de API.
  2. Ingrese orders para el nombre.
  3. En el panel Configuración, haga clic en Detalles de la API.
  4. Haga clic en el menú desplegable Método de solicitud y seleccione GET.
  5. Ingrese el URL para el URL de extremo.
  6. Para Autenticación, seleccione el método de autenticación.

    Si desea más información, consulte Creación de conexiones para la integración con servicios externos.

  7. Haga clic en Hacer llamada de API.
  8. Haga clic en Guardar junto a “results”.

  9. En el menú desplegable Valor, seleccione Order y luego Image.

    Utilice el nombre predeterminado de la variable (image).

  10. 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).

  11. Haga clic en Guardar.
Para crear el carrusel dinámico
  1. En el generador de bots, haga clic en Agregar paso bajo La llamada a la API se realizó correctamente y seleccione Agregar carrusel.
  2. En el panel Configuración, haga clic en Convertir a mensaje dinámico.
  3. En el menú desplegable Matriz, haga clic en results. Esta es la matriz que se creó anteriormente.
  4. 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.

  5. Para Vínculo del botón, haga clic en el signo de más y seleccione results.image.
  6. Para Texto del botón, haga clic en el signo de más y seleccione results.status.
  7. Para Vínculo de imagen, haga clic en el signo de más y seleccione results.image.
  8. 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 agente IA se dividen según si la solicitud de API se ejecutó correctamente.

El agente IA bajará en la rama de fallas en los siguientes casos:
  • La API devuelve un código de respuesta 400 o 500.
  • Falta una de las variables o bien tiene un valor null.

En todos los demás casos, el agente IA bajará en la rama de éxito.

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.
Tecnología de Zendesk