Utilisation de l’étape Effectuer un appel API dans un bot de conversation

Attention : Zendesk a modifié le nom de ses capacités de bot. Answer Bot s’appelle désormais bots Zendesk, le créateur de workflow est devenu le créateur de bots et les recommandations d’articles sont devenues les réponses automatiques. Certaines anciennes fonctionnalités utilisent l’ancienne terminologie, reflétée dans cette documentation. Pour en savoir plus sur ces changements, consultez cet avis.

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 bot de conversation

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

Cet article contient les sections suivantes :

• Ajout d’une étape Effectuer un appel API à votre bot
• 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 bot

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

Les procédures ci-dessous supposent que vous avez déjà créé un bot de conversation que vous ajoutez cette étape à ce bot.

Pour ajouter une étape Effectuer un appel API

1. Ouvrez le bot dans le créateur de bots.
2. Cliquez sur l’icône Ajouter nouv. à l’endroit où vous voulez insérer l’étape (à la fin d’une branche ou entre deux étapes existantes).
3. Dans le volet de configuration, cliquez sur Effectuer un appel API.
4. Saisissez des informations descriptives pour cette étape (votre équipe peut voir ces informations mais pas les clients) :
   • Nom : 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.
5. Continuez avec la procédure décrite dans la section Ajout des détails de l’API ci-dessous.

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. Dans le menu déroulant, sélectionnez une Méthode de la demande :
   • GET récupère les données à partir d’un serveur de la ressource externe. C’est la méthode le plus souvent utilisée.
   • POST envoie des données pour créer ou mettre à jour 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 ou créer une ressource. Si la ressource existe déjà, les données envoyées remplacent la 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 un en-tête associé à 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 bot de messagerie peut inviter un client à fournir un numéro de commande en utilisant l’étape Demander des détails. Le bot 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, le bot 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 huit variables dans une étape Effectuer un appel API.

Remarque – Seuls les 280 premiers caractères de la valeur d’une variable figurent dans la réponse affichée dans la conversation de messagerie.

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.

À 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 du bot sont divisées selon que l’exécution de l’API a réussi ou non.

Si l’API a renvoyé un code de réponse de 400, 500 ou 200 avec des données dans lesquelles manquent une ou plusieurs variables, le bot suivra la branche d’échec.

Attention : si vous utilisez l’étape Effectuer un appel API, vous comprenez et acceptez que le système externe auquel vous vous connectez est un service non proposé par Zendesk (tel que défini dans l’Accord sur les services principaux). 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.