Les intégrations d'API personnalisées permettent à votre chatbot d'obtenir des informations en temps réel depuis votre ERP, votre outil d'entrepôt, votre CRM ou un autre service. Elles peuvent également apporter des modifications, comme créer un rendez-vous. Une intégration enregistre l'URL de base ; chaque opération définit une requête exécutable. Vous associez ensuite les opérations sélectionnées à un chatbot en tant que actions IA.
Avant de commencer
Vérifiez que votre compte inclut les intégrations Custom API. Vous avez besoin de l'URL du point de terminaison, de la méthode HTTP, des noms et types de paramètres, des exigences d'authentification ainsi que d'un exemple de réponse. Le point de terminaison doit être accessible depuis les serveurs de ChatLab ; localhost sur votre ordinateur n'est pas un point de terminaison de production.
Utilisez HTTPS et un service de test ou des enregistrements de test pour la configuration. Une requête de test appelle réellement le point de terminaison, un POST, PATCH ou DELETE peut donc modifier des données externes. Rendez les opérations sûres à répéter dans la mesure du possible.
1. Créer une intégration
- Ouvrez Custom Integrations (Intégrations personnalisées) dans le menu de navigation principal.
- Cliquez sur + Define API Integration (+ Définir une intégration API).
- Saisissez API name (Nom de l'API) et API Base URL (URL de base de l'API), par exemple
https://api.example.com. - Cliquez sur Create API Integration (Créer l'intégration API).
- Dans son entrée de liste, cliquez sur View (Afficher), puis sur + Define API Operation (+ Définir une opération API).
2. Définir l'opération
Attribuez à l'opération un libellé reconnaissable et un nom lisible par la machine (Operation name - Nom de l'opération), tel que getProductDetails. Utilisez uniquement des lettres et des chiffres pour le nom de l'opération, sans espaces ni traits de soulignement. Décrivez ce que fait l'opération et à quel moment le chatbot doit l'utiliser.
Saisissez l'URI relative, par exemple /v1/products/@productId@. L'URL de base et l'URI constituent l'adresse de la requête.
Certaines captures d'écran existantes montrent des exemples de noms plus anciens ou des espaces réservés sous forme d'accolades. Suivez la syntaxe actuelle ci-dessous : des noms d'opération tels que getProductDetails et des espaces réservés de paramètres entourés de @.
Paramètres de chemin et de requête
Cliquez sur Add path variable (Ajouter une variable de chemin) pour définir productId. Définissez son type de données et sa source de valeur, puis incluez @productId@ dans l'URI. Les variables de chemin sont obligatoires, et chaque variable de chemin définie doit apparaître dans l'URI avant de pouvoir enregistrer ou tester.
Utilisez Add query parameter (Ajouter un paramètre de requête) pour les paramètres tels que limit ou language qui se placent après le point d'interrogation de l'URL. Saisissez le nom attendu par votre API, son type, sa description et sa source de valeur.
Les sources de valeur disponibles comprennent :
- Provided by user or chatbot (Fourni par l'utilisateur ou le chatbot) : le modèle fournit une valeur issue de la conversation. Expliquez le format attendu et marquez les valeurs obligatoires de manière appropriée.
- Constant (Constante) : une valeur configurée dans l'opération, telle qu'un identifiant de compte fixe ou un identifiant d'API restreint.
- Random value (Valeur aléatoire) : une valeur générée automatiquement.
- Client context (Contexte client) : une valeur transmise par le site web hôte, lorsqu'elle est disponible pour votre compte. Consultez l'article Chat API.
Les types scalaires incluent string, integer, double et boolean. Les paramètres du corps acceptent également les tableaux de chaînes (string) et d'entiers (integer).
3. Configurer la méthode et le corps
Choisissez GET, POST, PUT, PATCH ou DELETE selon votre point de terminaison. Pour les méthodes autres que GET, l'éditeur propose du contenu de requête raw (brut) ou form-data.
Pour un corps JSON brut, définissez les paramètres du corps et insérez leurs espaces réservés @name@ dans le modèle. Ajoutez l'en-tête Content-Type requis par votre point de terminaison. Par exemple, avec un paramètre de type chaîne name et un paramètre de tableau de chaînes tags :
{
"name": "@name@",
"tags": @tags@
}
Il s'agit d'un modèle et non d'un JSON littéral avant la substitution. Les espaces réservés de tableaux ne doivent pas être entourés de guillemets. Chaque paramètre de corps défini doit être utilisé dans le modèle lorsque l'éditeur de corps brut s'applique. Vérifiez la requête générée pendant les tests, y compris les textes contenant des guillemets ou des caractères spéciaux.
4. Ajouter les en-têtes d'authentification
Utilisez Add header (Ajouter un en-tête) pour définir les en-têtes attendus par l'API. Pour un jeton porteur (bearer token), utilisez le nom d'en-tête Authorization, la source de valeur Constant et la valeur Bearer YOUR_RESTRICTED_TOKEN.
Gardez les secrets hors des prompts et des URL. Évitez les opérations qui renvoient des jetons de connexion au modèle en comptant sur des instructions pour les masquer. Privilégiez un point de terminaison d'intégration côté serveur qui gère sa propre authentification et n'expose que l'opération autorisée.
5. Enregistrer et tester la requête
- Cliquez sur Save changes (Enregistrer les modifications) dans l'éditeur d'opérations. Contrairement aux paramètres habituels du chatbot (Settings), cet éditeur dispose d'un bouton d'enregistrement explicite.
- Cliquez sur Test API Operation (Tester l'opération API). Il est désactivé tant que des modifications ne sont pas enregistrées.
- Saisissez des valeurs de paramètres représentatives. Pour les entrées de test sous forme de tableau, utilisez des valeurs séparées par des virgules.
- Exécutez le test uniquement sur des données que vous êtes autorisé à lire ou à modifier.
- Examinez le code d'état, le corps de la réponse, l'URL de la requête, les en-têtes, le corps et tout avertissement affiché dans les résultats.
- Corrigez les erreurs, enregistrez et répétez si nécessaire.
Ne partagez pas de résultats de test contenant des identifiants. Renvoyez des données ciblées et paginées dans la mesure du possible : les réponses volumineuses peuvent être tronquées avant d'atteindre le modèle.
6. Associer l'opération à un chatbot
Ouvrez votre chatbot, puis allez dans Settings > Actions (Paramètres > Actions). Utilisez le bouton plus pour ajouter une action, recherchez votre opération sous les API personnalisées, puis associez-la ou activez-la. Créer une intégration au niveau du compte ne rend pas automatiquement chaque opération accessible à tous les chatbots.
Vérifiez les instructions de l'action ainsi que les paramètres de sécurité disponibles, puis attendez la confirmation de l'enregistrement. Consultez Actions de l'IA pour en savoir plus sur l'éditeur d'actions.
7. Expliquez quand l'utiliser
Ouvrez Settings > Role & Behavior (Paramètres > Rôle et comportement).
Si vous utilisez des instructions de rôle personnalisées, sélectionnez Custom Role Definition (Définition de rôle personnalisée) et ajoutez une règle précise, par exemple : « Lorsque le visiteur demande si un produit est en stock, appelez getProductDetails avec son identifiant de produit. Indiquez la disponibilité retournée. Si la recherche échoue, expliquez que la disponibilité n'a pas pu être vérifiée. »
Conservez les autres instructions utiles du chatbot. Attendez la confirmation de l'enregistrement, puis utilisez l'aperçu dans l'onglet Overview (Aperçu) pour tester des questions réalistes, des paramètres manquants, des erreurs ainsi que des requêtes non autorisées. Les conversations de test peuvent déclencher de véritables opérations.
L'appel par l'IA n'est pas garanti ni nécessairement unique. Effectuez des tests avec le modèle sélectionné pour votre chatbot ; ne supposez pas qu'un simple nom de modèle garantisse à lui seul une utilisation correcte de l'outil.
Sécurité et dépannage
Votre endpoint doit authentifier les requêtes et autoriser l'accès de chaque utilisateur avant de renvoyer des informations sensibles ou d'effectuer une modification. Un identifiant client, une adresse e-mail, un numéro de commande ou un champ de contexte fourni par le navigateur ne constitue pas une preuve d'identité suffisante. Si vous transmettez un token propre à chaque utilisateur via le contexte client, votre serveur doit le valider.
Ne renvoyez que les champs dont le chatbot a besoin, par exemple le statut de la commande plutôt qu'un profil client complet. Les instructions du prompt peuvent orienter la formulation, mais elles ne peuvent pas garantir que les données sensibles transmises au modèle resteront masquées.
Si la requête aboutit dans l'éditeur de test mais échoue dans une conversation, vérifiez l'action associée, son état d'activation, ses instructions, ses paramètres obligatoires et le contexte disponible. Si les deux échouent, examinez l'URL, la méthode HTTP, l'authentification, le corps rendu et les journaux de votre endpoint. Évitez de retenter à plusieurs reprises une opération d'écriture tant que vous ne savez pas si la requête précédente a abouti.