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
L’ajout d’une étape Effectuer un appel API à votre bot inclut plusieurs tâches distinctes.
Pour ajouter une étape Effectuer un appel API
- Ouvrez le bot dans le créateur de bots.
- 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).
- Dans le volet de configuration, cliquez sur Effectuer un appel API.
- 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.
- 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
- Dans le volet de configuration, cliquez sur Détails de l’API.
- 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.
- 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 Utilisation de l’étape Effectuer un appel API dans un bot de conversation. - (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.
- 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
oux-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. - 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. |
Les variables ne peuvent pas être ajoutées au domaine/sous-domaine. |
Récupérez un lieu via des recherches de mots-clés de l’API de lieux (Places) de Google. |
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.
Enregistrement des variables de la réponse API
Pour créer une variable à partir des données de réponse
- Dans le volet de configuration, cliquez sur Effectuer un appel API.
- 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.
- Cliquez sur Enregistrer.
- 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
{
"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",
…
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. 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.
{{customer.order}}
est vide. Pour la carte 1, la carte est rendue avec un titre partiel de « Order number ». Pour la carte 2, le titre est vide et la carte 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
{
"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"
},
…
Nous allons utiliser Effectuer un appel API pour créer la variable de tableau, puis utiliser un carrousel dynamique afin d’afficher les résultats pour un utilisateur final.
Pour créer le tableau
- Dans le volet de configuration, cliquez sur Effectuer un appel API.
- Saisissez commandes comme nom.
- Dans le volet de configuration, cliquez sur Détails de l’API.
- Si ce n’est pas encore fait, cliquez sur le menu déroulant Méthode de la demande et sélectionnez GET.
- Saisissez https://run.mocky.io/v3/b6c6180b-924c-407f-852d-9887d9a1641e pour l’URL du point de terminaison.
- Pour Authentification, sélectionnez Pas d'authentification. Si votre point de terminaison spécifique nécessite une authentification, sélectionnez une connexion existante ou créez-en une nouvelle. Pour en savoir plus, consultez Création de connexions d’API pour le créateur de bots.
- Cliquez sur Effectuer un appel API.
- Cliquez sur Enregistrer en regard de « results ».
- Dans le menu déroulant Value, sélectionnez Order, puis Image. Utilisez le nom de la variable par défaut (image).
- 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 (paires clé-valeur).
- Cliquez sur Enregistrer.
- Dans le créateur de bots, cliquez sur Ajouter une étape sous Appel API réussi et sélectionnez Ajouter un carrousel.
- Dans le volet Configuration, cliquez sur Convertir en message dynamique.
- Dans le menu déroulant Tableau, cliquez sur résultats. Il s’agit du tableau que vous avez créé plus haut.
- 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.
- Pour Lien du bouton, cliquez sur le signe + et sélectionnez results.image.
- Pour Texte du bouton, cliquez sur le signe + et sélectionnez results.status.
- Pour Lien vers l’image, cliquez sur le signe + et sélectionnez results.image.
- Cliquez sur Terminé.
- Ajoutez la réponse orders à votre bot.
- Cliquez sur Tester le bot.
À 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.