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
- Dans le Centre d’administration, cliquez sur
Canaux dans la barre latérale, puis sélectionnez Agents IA et automatismes > Agents IA. - Cliquez sur Gérer les bots de conversation.
- Cliquez sur le nom du bot à modifier.
- Cliquez sur l’onglet Réponses, puis créez une nouvelle réponse ou ouvrez une réponse existante
- 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).
- Dans le volet de configuration, cliquez sur Effectuer un appel API.
- 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.
- 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
- Dans le volet de configuration, cliquez sur Détails de l’API.
- 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.
- 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. - (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 des en-têtes associés à l’authentification, comme
authorizationoux-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.jsonRé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
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
- 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"
},
… 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
- 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.
- Cliquez sur le menu déroulant Méthode de la demande et sélectionnez GET.
- Saisissez l’URL pour l’URL du point de terminaison.
- Pour Authentification, sélectionnez votre méthode d’authentification.
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 (ou 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é.
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 du bot sont divisées selon que l’exécution de l’API a réussi ou non.
- L’API renvoie un code de réponse 400 ou 500.
- L’API renvoie un code de réponse 200 où l’une des variables enregistrées est manquante ou a une valeur
null.
Le bot suivre la branche de réussite dans tous les autres cas.