Mon édition
Module supplémentaire Agents IA - avancé

Le créateur d’intégration est un outil puissant, qui ne nécessite aucun code et vous permet de connecter votre agent IA à n’importe quelle API ou source de données, sans compétences techniques ou de programmation particulières. Personnalisez vos expériences de chat et boostez vos résolutions automatisées grâce au contenu dynamique.

Imaginez un agent IA capable d’accéder à vos informations client à partir de votre système back-office, de récupérer des données à partir de n’importe quelle source de données externe et d’interagir avec des applications tierces, sans que vous ayez à écrire une seule ligne de code.

Avec ses capacités de contenu dynamique, le créateur d’intégration permet de récupérer, d’analyser et de transformer les données en temps réel : ainsi, votre agent IA peut fournir des réponses, des recommandations et des solutions personnalisées, adaptées aux besoins spécifiques de chaque utilisateur.

Avec son interface conviviale, ses fonctionnalités intuitives et son fonctionnement « sans code », le créateur d’intégration offre une souplesse et une personnalisation optimales, sans nécessiter de connaissances techniques approfondies.

Dans cet article, nous allons voir les fonctionnalités clés et les avantages du créateur d’intégration. Vous trouverez aussi un guide détaillé, expliquant comment exploiter ses capacités pour connecter votre agent IA à n’importe quelle API ou source de données.

  • Mise en route
  • Paramètres de la demande
  • Environnements
  • Fonctionnalité de test
  • Scénarios

Mise en route

Pour accéder au créateur d’intégration, il vous suffit de cliquer sur Intégrations d’API dans le menu de navigation latérale. Vous verrez alors une liste, dans laquelle toutes vos intégrations futures sont répertoriées et accessibles. Selon votre parcours d’intégration initiale, vous commencerez soit sans intégration d’API, soit avec un exemple d’intégration d’API.

Pour créer une intégration, cliquez sur Ajouter une intégration en haut à droite.
Saisissez un nom pour l’intégration.
Ajoutez une courte description avec des informations contextuelles supplémentaires.

Remarque – Pour que les API soient utilisées par un agent IA agentique au bon moment et dans le bon contexte, il est primordial d’ajouter une description claire et précise. Votre description doit inclure ce qu’est l’API, comment l’utiliser, et la définition des différents paramètres.

Quand vous avez terminé, cliquez sur Enregistrer pour aller à la page de configuration de l’intégration.

Screenshot

Si vous ne voyez pas les intégrations d’API dans la navigation latérale, vous n’êtes probablement pas un administrateur client. Actuellement, l’accès au créateur d’intégration est réservé aux administrateurs clients. Dans ce cas, contactez votre chargé de compte pour discuter de vos droits d’accès.

Vous trouverez aussi une vidéo d’introduction réalisée par Chloe, qui fait partie de notre équipe d’ingénierie personnalisée, ci-dessous.

Paramètres de la demande

Pour commencer, vous devez configurer les paramètres de la demande nécessaires pour obtenir une réponse de l’API. Ces paramètres contiennent des informations dérivées de la conversation et servent à définir les détails de la demande d’API. Par exemple, si vous voulez récupérer des informations utilisateur spécifiques à afficher pendant la conversation, vous devez absolument inclure l’ID utilisateur à la demande. Cela garantit que la réponse de l’API contient les informations concernant l’utilisateur ou le visiteur pertinent qui participe au chat.

Voici un exemple de configuration des paramètres de la demande :

Screenshot

En plus de spécifier la clé et le type de paramètre de la demande, vous pouvez définir une valeur test. Nous vous conseillons vivement de le faire, car cette valeur test sera utilisée pendant la configuration si vous utilisez la fonctionnalité de test accessible en haut à droite de l’écran. Pendant une conversation en direct réelle, la valeur est transmise à l’intégration d’API avant d’effectuer la demande. Cependant, comme le contexte de la conversation en direct actuelle manque, une valeur test est nécessaire pour que l’appel API réussisse.

Les cases à cocher obligatoires vous permettent de déterminer si le paramètre de la demande est facultatif ou obligatoire avant d’appeler les intégrations d’API dans la conversation, s’il n’a pas déjà été enregistré dans la session.

L’inclusion de paramètres de la demande dépend des exigences spécifiques de l’API concernée par l’appel. Pour certaines API, les paramètres de la demande sont ajoutés à la fin de l’URL. Pour d’autres, ils sont inclus dans l’en-tête ou le corps de la demande. Consultez la documentation de votre API pour déterminer si vous devez inclure le paramètre de la demande. Une fois que vous l’avez déterminé, vous pouvez ajouter le paramètre de la demande à l’URL, à l’en-tête ou au corps de la demande en référençant la clé entre doubles accolades - {{userID}}.

Screenshot

Environnements

Une fois le paramètre de la demande ajouté, vous pouvez effectuer la configuration principale de l’appel API dans la section d’environnement. En regard du nom de l’environnement qui apparaît quand vous testez l’intégration ou la référencez dans le DLB, vous devez choisir la méthode, l’URL et le type d’autorisation en fonction de la documentation de l’API sous-jacente. 

Types d’autorisation

Nous proposons les types d’autorisation suivants :

Type d’autorisation Description Exemple
Clé API Une clé API simple qui devrait être fournie par le propriétaire de l’API.
Token du porteur Un autre token qui devrait être fourni par le propriétaire de l’API.
Authentification de base Un nom d’utilisateur et un mot de passe sont utilisés pour l’authentification avec l’API.
OAuth 2.0 Diverses informations d’authentification sont nécessaires en fonction du type d’octroi. Screenshot
Personnalisée Autorisation via un token d’expiration. Consultez Utilisation de l’autorisation personnalisée avec le créateur d’intégration.

N’oubliez pas d’inclure le token d’autorisation à la demande en l’ajoutant sous la forme {{apiToken}} aux en-têtes pour tous les types d’autorisation (sauf Pas d’autorisation). Consultez la section sur les en-têtes pour un exemple. 

En-têtes

Les en-têtes contiennent des informations supplémentaires sur la demande ou le client et le serveur communiquant entre eux. Il s’agit de paires clé-valeur incluses dans la section d’en-tête de la demande. Voici quelques en-têtes couramment utilisés :

  • Content-Type : indique le format des données dans le corps de la demande (p. ex., JSON, XML, données de formulaire).
  • Authorization : fournit des identifiants ou des tokens pour authentifier le client qui fait la demande.
  • User-Agent : spécifie l’agent utilisateur qui initie la demande, généralement le navigateur Web ou l’application client.
  • Accept : informe le serveur des formats de réponse acceptés par le client.
  • Cache-Control : définit les directives de mise en cache pour le serveur ou les caches intermédiaires.
  • X-Requested-With : identifie le type de demande (p. ex., XMLHttpRequest, Fetch API) faite par le client.

Screenshot

Corps 

Le corps d’une demande d’API contient les données envoyées à l’API. Il est généralement utilisé dans les demandes qui nécessitent des données d’entrée pour le traitement ou la manipulation des données côté API. Le corps peut contenir divers formats, comme JSON, XML, du texte brut ou des données de formulaire, en fonction de l’API et du point de terminaison spécifique sur lesquels porte l’appel. Dans notre cas, pour l’instant, nous ne prenons que JSON en charge. 

Screenshot 2023-09-22 at 13.13.47.png

Gestion des environnements

Pour vous aider à gérer les environnements de sandbox et de production pour les API, nous avons incorporé le concept d’environnements au créateur d’intégration. En plus de l’environnement principal qui est créé automatiquement quand vous configurez une intégration, vous pouvez inclure des environnements supplémentaires.

Ces environnements supplémentaires vous permettent de personnaliser l’URL, les détails d’authentification, les en-têtes et le corps des demandes, et ainsi de cibler des environnements de sandbox ou de production spécifiques au sein de votre API. 

Pour créer un environnement, cliquez sur le bouton + en regard de la section Environnement. Si vous voulez répliquer un environnement existant, placez votre curseur dessus, cliquez sur les trois points pour ouvrir le menu et choisissez l’option Dupliquer. N’oubliez pas que vous ne pouvez définir qu’un seul environnement comme environnement par défaut. Il s’affiche en haut de la liste et est automatiquement sélectionné en premier dans le DLB (sauf si cela a été modifié intentionnellement). 

Screenshot

Si un environnement n’est pas utilisé par les agents IA et qu’il s’agit du seul environnement ou de l’environnement par défaut, il peut être supprimé. Pour modifier les paramètres par défaut, cliquez sur les trois points pour ouvrir le menu et sélectionnez l’option de votre choix.

Screenshot

Fonctionnalité de test

Une fois que vous avez terminé la configuration de la demande d’API, il est utile de vérifier que toutes les configurations sont correctes. Pour ce faire, le créateur d’intégration inclut une fonctionnalité de test pratique que vous trouverez en haut à droite de l’écran.

Le bouton de test est signalé par le mot Test, suivi du nom de l’environnement par défaut. Si vous cliquez dessus, le créateur d’intégration initie une demande d’API en utilisant les informations fournies dans les sections de paramètres de la demande et d’environnement. La réponse reçue de l’API s’affiche alors dans la section Test de l’intégration sur le côté droit de l’interface. Si vous voulez tester l’API en utilisant les détails de la demande d’un autre environnement, sélectionnez l’environnement de votre choix dans le menu déroulant de la fonctionnalité de test et cliquez à nouveau sur le bouton Test.

Screenshot

Contenu de la réponse

Dans la section Test de l’intégration, le créateur d’intégration présente la réponse de l’API. Le contenu de la réponse est organisé dans les objets suivants : 



Objets Contenu Exemple
statusCode Les codes de statut de réponse HTTP indiquent si une demande HTTP spécifique a réussi. En savoir plus.  "statusCode": 200
data L’objet data présente les données pertinentes de l’API si la demande réussit. Cependant, si la demande échoue, il fournit des données supplémentaires basées sur les codes de statut correspondants.

"data": {

   "name": "Germany",

   "capital": "Berlin",

   "region": "Europe",

   "population": 83240525,

   "area": 357114 }

requestParameters Dans l’objet requestParameters, le créateur d’intégration présente les paramètres de demande, en plus des valeurs de test associées utilisées pour invoquer l’API.

"requestParameters": {

   "country": "de"}

Avant de réutiliser la fonctionnalité de test pour examiner l’intégration avec les configurations modifiées, n’oubliez pas d’enregistrer l’intégration.

Screenshot

Scénarios

Chaque nouvelle intégration inclut trois scénarios préconfigurés. Deux d’entre eux peuvent être personnalisés ou supprimés en fonction de vos besoins, mais le troisième, intitulé « Fallback », ne peut pas être modifié. Ce scénario sert d’option de repli principale si aucun des scénarios précédents n’est déclenché.

Scénario Requête par défaut Description
Success statusCode >= 200 et statusCode < 300 Le scénario qui devrait capturer le chemin de réussite si le code de statut est compris entre 200 et 300. 
Failure statusCode < 200 ou statusCode >= 300 Le scénario qui devrait capturer le chemin d’échec si le code de statut n’est pas compris entre 200 et 299. 
Fallback -  Scénario de repli pour qu’au moins un scénario se déclenche systématiquement.

Les scénarios sont équivalents aux différentes branches que suit la conversation dans le dialogue quand l’intégration d’API est déclenchée. 

Screenshot

Requêtes de scénario

Un seul scénario peut être déclenché par intégration d’API. La logique qui permet de déterminer quel scénario est déclenché pendant une conversation est basée sur les requêtes de scénario et l’ordre dans lequel sont définis les scénarios.

Les requêtes de scénario représentent les conditions qui doivent être satisfaites pour qu’un scénario spécifique soit déclenché. Pour déterminer si une condition est vraie, le créateur d’intégration examine la requête de scénario et les données contenues dans la réponse de l’API. Les champs de données couramment utilisés incluent les codes de statut, les données spécifiques à l’API dans l’objet data de la réponse de l’API et parfois même des valeurs provenant des paramètres de la demande. 

Screenshot

La requête par défaut du scénario Success exige que le code de statut de la réponse de l’API soit compris entre 200 et 300. Si cette condition est satisfaite, le scénario Success est déclenché.

Comme les requêtes de scénario par défaut peuvent être modifiées et que de nouveaux scénarios peuvent être ajoutés, il est possible que plusieurs requêtes de scénario de différents scénarios soient vraies en fonction de la réponse de l’API. Dans ce cas, l’ordre des scénarios détermine le scénario qui sera déclenché.

Pour fournir un feedback visuel, nous avons mis en œuvre une fonctionnalité qui indique le scénario qui serait déclenché en fonction de la réponse de l’API actuelle. Vous pouvez aussi voir les scénarios qui devraient, en théorie, être déclenchés, mais qui ne le sont pas, car un scénario qui apparaît avant eux dans le classement par ordre est déclenché. En outre, les scénarios qui ne seraient pas déclenchés, car leurs conditions ne sont pas satisfaites, apparaissent en surbrillance.

Correspondance des critères Visualisation Description
Les critères correspondent au premier scénario dans l’ordre. Screenshot Le scénario signalé par un point bleu plein représente le scénario qui serait déclenché.
Les critères ne correspondent pas. Screenshot Le ou les scénarios signalés par un point vide ne seront pas déclenchés.
Les critères correspondent, mais pas au premier scénario dans l’ordre. Screenshot Le ou les scénarios signalés par un point gris plein ne seraient déclenchés que théoriquement.

Pour modifier l’ordre des scénarios, cliquez sur un scénario et déplacez-le en le faisant glisser. À l’exception du scénario de repli (Fallback), qui reste toujours en dernière position, vous pouvez réagencer les scénarios dans l’ordre de votre choix.

Paramètres de session

Quand vous configurez chaque scénario, vous pouvez améliorer la conversation avec divers points de données de vos systèmes back-end. Vous pouvez spécifier les données que vous voulez rendre accessibles à chaque scénario en transformant et stockant les informations pertinentes de la réponse de l’API sous la forme de paramètres de session. Ces paramètres de session peuvent alors être utilisés dans le processus de création de dialogue pour présenter les informations aux visiteurs ou pour cartographier le workflow sous-jacent.

Un paramètre de session est défini par une paire clé-valeur. La clé sert de référence dans le créateur de dialogue et la requête sert à transformer et extraire des données spécifiques de la réponse de l’API pour enregistrer la valeur. Le créateur d’intégration fournit du feedback en temps réel sur la façon dont la valeur enregistrée apparaîtra dans le champ de valeur de réponse en fonction de la valeur de réponse actuelle.

Screenshot

Dans l’illustration ci-dessus, le paramètre de session est défini comme « capital » et peut être référencé dans le DLB en utilisant des accolades doubles - {{capital}}. La requête détermine quelles données doivent être transformées et enregistrées comme valeur pour le paramètre de session. Dans ce cas, elle extrait le contenu du champ « capital » au sein de l’objet data de la réponse de l’API.

Langage de requête - JSONata

JSONata sert de langage de requête pour les requêtes au niveau du scénario et au niveau de la session. Ce langage est conçu en s’appuyant sur le concept que les requêtes simples devraient être faciles à rédiger et à la portée de tous les professionnels, qu’ils maîtrisent la technologie ou non. JSONata est facile et rapide à apprendre et comprendre. Avec JSONata, vous pouvez exécuter des fonctions élémentaires, transformer des dates et même fusionner des points de données.

Screenshot 2024-02-21 at 09.21.32.png

JSONata est un langage de requête et de transformation documenté et vous pouvez trouver toute la documentation utile ici. 

Réalisé par Zendesk