Actions API personnalisées

Les actions API personnalisées permettent à votre agent d'appeler un endpoint HTTP externe lors d'une conversation et d'utiliser la réponse pour répondre au visiteur. Utilisez cette fonctionnalité pour rechercher le statut d'une commande, vérifier les stocks, récupérer les détails d'un compte ou interroger n'importe quelle API interne.

Créer une action

Rendez-vous dans Capacités → Actions API personnalisées et cliquez sur Ajouter une action.

Paramètres généraux

• Nom — comment l'IA appelle cette action en interne. Gardez-le court et descriptif : Vérifier le statut de commande, Obtenir la disponibilité du produit.
• Quand utiliser — description en anglais simple indiquant quand l'IA doit déclencher cette action.

Utiliser cette action lorsque le visiteur demande le statut de sa commande ou souhaite suivre une livraison.

Configurer l'appel API

Méthode et URL

Sélectionnez la méthode HTTP (GET, POST, PUT, PATCH, DELETE) et saisissez l'URL de l'endpoint. Utilisez des {{espaces réservés}} pour les valeurs dynamiques :

https://api.votreboutique.com/orders/{{order_id}}

Données d'entrée

Définissez les variables dont votre URL, en-têtes ou corps ont besoin. Pour chaque entrée :

Exemple pour la recherche d'une commande :

• Nom : order_id · Description : Le numéro de commande fourni par le visiteur · Obligatoire : oui

L'IA extrait les valeurs du contexte de la conversation automatiquement. Si une valeur obligatoire manque, l'IA la demande au visiteur avant d'effectuer l'appel.

En-têtes, Paramètres, Corps

Utilisez les onglets pour ajouter des en-têtes d'autorisation, des paramètres de requête ou un corps de requête. Les espaces réservés fonctionnent partout :

Authorization: Bearer {{api_token}}

Pour les secrets statiques (comme les tokens API) que vous ne souhaitez pas extraire du chat, saisissez-les directement comme valeurs sans espace réservé — ils ne seront pas exposés à l'IA ni aux visiteurs.

Tester l'action

Dans la section Tester la réponse, saisissez des exemples de valeurs pour vos entrées et cliquez sur Lancer le test. L'appel HTTP réel est effectué et la réponse est affichée. Utilisez cette option pour vérifier que votre URL et votre authentification sont correctes avant la mise en production.

Accès aux données

Contrôle quelles parties de la réponse API l'IA peut voir :

• Complet — la réponse JSON entière est transmise à l'IA. Utilisez pour les réponses simples où tous les champs sont nécessaires.
• Limité — seuls les champs que vous mettez sur liste blanche sont transmis à l'IA. Utilisez cette option pour protéger les données sensibles (identifiants internes, tokens, données personnelles) d'être incluses dans les réponses de l'IA.

Saisissez les chemins de champs un par ligne en utilisant la notation pointée :

order.status
order.estimated_delivery
customer.name

Conseils

• Gardez les réponses concises — l'IA résume la réponse lorsqu'elle répond, donc une réponse ciblée donne de meilleurs résultats qu'un objet à 200 champs.
• Utilisez l'accès aux données Limité pour toute API qui retourne des champs sensibles aux côtés de ceux dont vous avez besoin.
• Si votre API nécessite OAuth, utilisez un token de service longue durée plutôt qu'un token utilisateur — l'action s'exécute sur le serveur de BotChata, pas dans le navigateur du visiteur.
• La syntaxe {{espace réservé}} fonctionne dans : le chemin d'URL, les paramètres de requête, les en-têtes et le corps de la requête.