Utilisation de l’étape Effectuer un appel API dans un agent IA pour la messagerie (legacy)

Mon édition

Suite

Team, Growth, Professional, Enterprise ou Enterprise Plus

Cet article décrit une fonctionnalité réservée aux clients qui avaient créé ou publié des agents IA avant le 2 février 2025. Pour en savoir plus sur la fonctionnalité équivalente dans le module supplémentaire Agents IA - Avancé, consultez Intégration d’autres plateformes aux agents IA - Avancé.

L’étape Effectuer un appel API vous permet de configurer un appel API à un autre système, un système CRM ou ERP par exemple, ou de transférer les détails d’une conversation à un point de terminaison externe, comme Amazon Event Bridge ou Google Analytics.

Dans cet article, nous allons voir les procédures permettant d’inclure et de configurer cette étape dans un agent IA pour la messagerie

Pour un aperçu de l’étape Effectuer un appel API et de ses règles de configuration, consultez Types d’étape d’agent IA : Effectuer un appel API.

Cet article contient les sections suivantes :

• Ajout d’une étape Effectuer un appel API à votre agent IA
• Ajout des détails de l’API
• Enregistrement des variables de la réponse API
• À propos des branches de l’étape

Ajout d’une étape Effectuer un appel API à votre agent IA

L’ajout d’une étape Effectuer un appel API à votre agent IA inclut plusieurs tâches distinctes.

Les procédures ci-dessous supposent que vous avez déjà créé un agent IA pour la messagerie et que vous ajoutez cette étape à cet agent IA.

Remarque – Si le système appelé ne répond pas dans un délai de 10 secondes, l’appel est interrompu.

Pour ajouter une étape Effectuer un appel API

1. Dans le Centre d’administration, cliquez sur IA () dans la barre latérale, puis sélectionnez Agents IA > Agents IA.
2. Cliquez sur Gérer les agents IA pour la messagerie.
3. Cliquez sur l’agent IA à modifier.
4. Cliquez sur l’onglet Réponses, puis créez une nouvelle réponse ou ouvrez une réponse existante
5. Dans le créateur de bots, cliquez sur l’icône Ajouter une étape à l’endroit où vous voulez insérer l’étape (à la fin d’une branche ou entre deux étapes existantes).
6. Dans le volet de configuration, cliquez sur Effectuer un appel API.
7. Saisissez des informations descriptives pour cette étape
   • Name : un nom pour l’appel qui permet à votre équipe de l’identifier facilement.
   • Description (facultatif) : une courte description de l’action qu’effectue l’appel.

   Ces informations ne sont pas visibles par les clients.

8. Continuez avec la procédure décrite dans la section Ajout des détails de l’API.

Ajout des détails de l’API

Utilisez la section Détails de l’API pour configurer l’appel HTTP que vous voulez effectuer, notamment la méthode de la demande HTTP, l’emplacement de la source externe et des en-têtes supplémentaires si besoin est. Les étapes ci-dessous sont la suite de la procédure de la section précédente.

Pour ajouter les détails de l’API

1. Dans le volet de configuration, cliquez sur Détails de l’API.
2. Sélectionnez la méthode de la demande.
   • GET récupère une ressource externe du service API. C’est la méthode le plus souvent utilisée.
   • POST envoie des données pour créer une ressource dans un système externe. Si la ressource existe déjà, les données envoyées modifient la ressource.
   • PUT envoie des données pour mettre à jour une ressource.
   • PATCH envoie des données pour mettre à jour une ressource sur un site externe. Cette méthode sert à appliquer des modifications partielles à la ressource.
   • DELETE supprime la ressource de l’emplacement externe.
3. Saisissez une URL du point de terminaison.

   L’URL du point de terminaison est l’emplacement de la ressource externe à laquelle vous vous connectez. L’URL de point de terminaison prend en charge le protocole https://. Vous pouvez inclure des variables dans le chemin de l’URL ou dans les valeurs de chaînes de la requête. Pour en savoir plus, consultez Transfert de variables dans un appel API.

4. (facultatif) Sélectionnez une connexion pour l’authentification de l’appel API.
   Remarque – Vous devez créer une connexion avant de l’utiliser dans l’étape Effectuer un appel API.
5. Si besoin est, saisissez la clé et la valeur pour un en-tête facultatif.
   Important : n’utilisez pas les en-têtes pour l’authentification. Utilisez plutôt les connexions API.

   Les étapes Effectuer un appel API, qui incluent des en-têtes associés à l’authentification, comme authorization ou x-api-key, échouent automatiquement. En cas d’échec de l’étape Effectuer un appel API, la conversation suit la branche Échec de l’appel API de l’étape.

6. Cliquez sur Effectuer un appel API pour tester l’appel API.

   Si des variables sont ajoutées à l’URL ou à son l’URL, vous pouvez inclure des données de test facultatives pour votre service externe afin de vérifier le bon fonctionnement de l’appel API. Notez que cela effectuera une demande HTTP vers l’URL de point de terminaison configurée.

Transfert de variables dans un appel API

Quand vous saisissez une URL du point de terminaison pour un appel API, vous pouvez inclure des variables dans le chemin de l’URL ou dans les valeurs de chaînes de la requête. Cela vous permet de transférer des données de la conversation à un système externe.

Par exemple, un agent IA pour la messagerie peut inviter un client à fournir un numéro de commande en utilisant l’étape Demander des détails. L’agent IA peut ensuite utiliser une étape Effectuer un appel API pour obtenir le statut de livraison de la commande auprès de votre magasin en ligne.

Vous ne pouvez pas utiliser de variables dans le domaine ou sous-domaine d’une URL du point de terminaison. Le tableau suivant inclut des exemples de valeurs d’URL du point de terminaison valides et non valides.

URL du point de terminaison valide	URL du point de terminaison non valide
https://myshopify.com/admin/api/orders/order_number.json Récupérez une commande en spécifiant l’ID de la commande sur Shopify.	https://domain.com/api/search?input=value Les variables ne peuvent pas être ajoutées au domaine/sous-domaine.
https://maps.googleapis.com/maps/api/place?input=city_name Récupérez un lieu via des recherches de mots-clés de l’API de lieux (Places) de Google.	https://example.com/api/search?key=value Les variables ne peuvent pas être ajoutées à la clé de la chaîne de requête.

Si une variable est vide ou n’est pas valide, l’agent IA ignore cette variable pendant une conversation.

Remarque – Les valeurs des variables ne sont pas automatiquement traduites. Ne l’oubliez pas si vous utilisez la traduction automatique dans vos conversations de messagerie.

Enregistrement des variables de la réponse API

Après avoir configuré les détails et testé l’appel API, vous pouvez enregistrer les valeurs de la réponse JSON de l’appel API sous la forme de variables. Vous pouvez enregistrer un maximum de 12 variables dans une étape Effectuer un appel API. Seuls les 280 premiers caractères de la valeur d’une variable sont enregistrés.

Pour créer une variable à partir des données de réponse

1. Dans le volet de configuration, cliquez sur Effectuer un appel API.
2. Développez l’accordéon et identifiez les données provenant du système externe que vous voulez convertir en variable.
   Conseil : cliquez sur l’onglet Corps de la réponse pour voir la réponse brute renvoyée par le système externe.
3. Cliquez sur Enregistrer.
4. Donnez un nom à la nouvelle variable.

   Les noms de variables ne peuvent inclure que des lettres minuscules, des chiffres et des traits de soulignement.

Transfert de variables de tableau dans un appel API

Vous pouvez transférer des variables de tableau en utilisant Effectuer un appel APl et en fournissant l’URL du système externe. Le système externe doit avoir un point de terminaison d’API. Un point de terminaison d’API est une URL à laquelle l’API reçoit les demandes et envoie les réponses, ce qui permet à deux systèmes d’interagir. Les réponses sont rendues au format JavaScript Object Notation (JSON), comme illustré dans l’exemple suivant.

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

Seuls les premiers éléments de la variable de tableau s’affichent dans le Centre d’administration pour vous aider à visualiser les données renvoyées. Par exemple, dans la sortie JSON ci-dessus, id, name, address, item, price et image s’affichent tous. Ces données sont généralement transférées à un carrousel, mais ce dernier ne peut pas afficher plus de 10 éléments.

Remarque – Seuls les 280 premiers caractères de la valeur d’une propriété s’affichent dans la réponse.

Les tableaux JSON imbriqués peuvent également être enregistrés sous la forme de variables de tableau. Par exemple, avec la sortie JSON suivante, lastname et firstname peuvent être enregistrés sous la forme de deux variables indépendantes.

"name": 
   {
      "lastname": "Cummings”,
      "firstname": “Alexander"
   },
    

Vous ne pouvez pas modifier le tableau ou les valeurs du tableau au sein de la configuration du carrousel dans le Centre d’administration. Si vous avez besoin de modifier des données, vous devez supprimer le tableau dans le Centre d’administration et en créer un nouveau.

Si la variable renvoyée est nulle, l’élément ne s’affiche pas dans le carrousel. Par exemple, dans le scénario suivant, supposons que la valeur de la variable {{customer.order}} est vide. Pour la fiche 1, la fiche est rendue avec un titre partiel de « Order number ». Pour la fiche 2, le titre est vide et la fiche 2 n’est donc pas rendue.

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}}
    

Exemple

Dans cet exemple, une variable de tableau est créée en utilisant un point de terminaison d’API qui renvoie un tableau de commandes. Le tableau de commandes est spécifié par la propriété « results » dans le snippet de réponse d’API suivant.

     {
  "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"
   },
…   

Cet exemple utilise Effectuer un appel API pour créer la variable de tableau, puis utilise un carrousel dynamique afin d’afficher les résultats pour un utilisateur final.

Pour créer le tableau

1. Dans le volet de configuration, cliquez sur Effectuer un appel API.
2. Saisissez commandes comme nom.
3. Dans le volet de configuration, cliquez sur Détails de l’API.
4. Cliquez sur le menu déroulant Méthode de la demande et sélectionnez GET.
5. Saisissez l’URL pour l’URL du point de terminaison.
6. Pour Authentification, sélectionnez votre méthode d’authentification.

   Pour en savoir plus, consultez Création de connexions pour l’intégration avec des services externes.

7. Cliquez sur Effectuer un appel API.
8. Cliquez sur Enregistrer en regard de « results ».

   

9. Dans le menu déroulant Value, sélectionnez Order, puis Image.

   Utilisez le nom de la variable par défaut (image).

10. Cliquez sur Add item et répétez l’étape ci-dessus pour créer des éléments pour Order Status et Élément.

    Vous pouvez ajouter un maximum de 12 éléments (ou paires clé-valeur).

    

11. Cliquez sur Enregistrer.

Pour créer le carrousel dynamique

1. Dans le créateur de bots, cliquez sur Ajouter une étape sous Appel API réussi et sélectionnez Ajouter un carrousel.
2. Dans le volet Configuration, cliquez sur Convertir en message dynamique.
3. Dans le menu déroulant Tableau, cliquez sur résultats. Il s’agit du tableau que vous avez créé plus haut.
4. Pour le titre, cliquez sur le signe + et sélectionnez results.item.

   Vous pouvez saisir un maximum de 128 caractères pour le titre et la description.

5. Pour Lien du bouton, cliquez sur le signe + et sélectionnez results.image.
6. Pour Texte du bouton, cliquez sur le signe + et sélectionnez results.status.
7. Pour Lien vers l’image, cliquez sur le signe + et sélectionnez results.image.
8. Cliquez sur Terminé.

   

Voici un exemple de carrousel dynamique :

À propos des branches de l’étape

L’étape Effectuer un appel API est une étape d’embranchement. Quand vous ajoutez cette étape, les réponses de l’agent IA sont divisées selon que l’exécution de la demande API a réussi ou non.

L’agent IA suivra la branche d’échec dans les cas suivants :

• L’API renvoie un code de réponse 400 ou 500.
• L’une des variables enregistrées manque ou a une valeur null.

L’agent IA suivra la branche de réussite dans tous les autres cas.

Si vous utilisez l’étape Effectuer un appel API, vous comprenez et acceptez que le système externe auquel vous vous connectez soit un service non proposé par Zendesk (tel que défini dans le Contrat Cadre de Service). Zendesk n’exécute pas et ne contrôle pas les services non proposés par Zendesk activés via l’utilisation de la fonctionnalité d’extensions du créateur de bots et Zendesk n’est pas responsable des obligations de conformité légales ou réglementaires, qu’elles vous concernent ou qu’elles concernent les services non proposés par Zendesk.