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 workflow d’assistant.
Pour un aperçu de l’étape Effectuer un appel API et de ses règles de configuration, consultez Types d’étape d’assistant : Effectuer un appel API.
Cet article contient les sections suivantes :
Ajout d’une étape Effectuer un appel API à votre assistant
L’ajout d’une étape Effectuer un appel API à votre assistant inclut plusieurs tâches distinctes.
Les procédures ci-dessous supposent que vous avez déjà créé un workflow d’assistant et que vous ajoutez cette étape à cet assistant.
Pour ajouter une étape Effectuer un appel API
- Ouvrez l’assistant dans le Créateur de workflow.
- 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://. - (facultatif) Sélectionnez une connexion pour l’authentification de l’appel API. Remarque – Vous devez créer une connexion avant d’authentifier l’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
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.
Enregistrement de la réponse API sous la forme d’une variable
Une variable est une façon de stocker les réponses API. Vous pouvez utiliser les variables de plusieurs façons différentes :
- Personnalisation du message de l’assistant aux clients. Par exemple, vous pouvez enregistrer le nom d’un client sous la forme d’une variable et y faire référence dans un message de l’assistant. Vous pouvez ajouter des variables à n’importe quel point du workflow après l’étape Effectuer un appel API dans laquelle la variable a été créée, dans les étapes qui incluent un message configurable :
-
Transfert des données de l’appel à un système externe. Par exemple, vous pouvez inviter un client à fournir un numéro de commande, puis effectuer un appel API à votre système d’e-commerce pour le statut de livraison de cette commande spécifique. Quand vous utilisez des variables pour l’étape Effectuer un appel API, il existe quelques restrictions dont vous devez avoir conscience.
Dans le champ URL du point de terminaison, les variables peuvent uniquement être ajoutées au chemin de l’URL ou aux valeurs de chaîne de requête. Elles ne peuvent pas être utilisées dans la partie domaine ou sous-domaine de l’URL. Le tableau ci-dessous montre des exemples de ce que vous pouvez faire ou non avec les variables :
Configuration valide Configuration 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.
https://domain.com/api/search?input=valueLes variables ne peuvent pas être ajoutées au domaine/sous-domaine.
https://maps.googleapis.com/maps/api/place?input=city_nameRé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=valueLes variables ne peuvent pas être ajoutées à la clé de la chaîne de requête.
Si une variable n’est plus valide (si le schéma de l’API est modifié par exemple), l’assistant ignorera la variable lors de l’affichage à l’utilisateur final. Vous pouvez créer un maximum de huit variables dans une étape Effectuer un appel API.
Après avoir configuré les détails de l’API et testé l’appel API, vous pouvez utiliser les données de réponse renvoyées pour créer vos variables. Les étapes ci-dessous sont la suite de la procédure de la section précédente.
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.
Authentification de l’appel API
À l’étape Effectuer un appel API, vous pouvez utiliser une connexion pour authentifier les appels API auprès du service ou système externe.
Pour ce faire, vous devez d’abord créer la connexion dans le Centre d’administration. Une connexion vous permet de stocker et transférer les identifiants du service en toute sécurité. Consultez Création de connexions dans le Centre d’administration pour en savoir plus et des instructions détaillées.Si vous n’arrivez pas à ajouter la connexion, consultez le journal des audits dans le Centre d’administration pour en savoir plus.
À 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’assistant sont divisées selon que l’exécution de l’API a réussi ou non.
Au moment de l’exécution de l’assistant, tous les codes de réponse 200 enverront l’assistant vers la branche de réussite. Tous les codes de réponse 400 ou 500 enverront l’assistant vers la branche d’échec. Si l’API a renvoyé 200 avec une réponse vide, toutes les variables enregistrées à partir de cette étape seront ignorées à l’exécution.
0 Commentaires
Vous devez vous connecter pour laisser un commentaire.