Configurer des outils personnalisés pour le Capitaine

Découvrir

Les outils personnalisés permettent à l’assistant d’appeler vos propres systèmes pendant une conversation, par exemple pour vérifier une commande, une garantie ou une réservation, au lieu de transférer la demande.

Forfait & accès : Business ou Enterprise (Tarifs & forfaits). Sur Startups, Outils affiche généralement Mettre à niveau pour utiliser les outils avec Captain. Chaque assistant dispose de sa propre liste d’outils. Les administrateurs créent les outils, et seuls les administrateurs peuvent voir les identifiants enregistrés. En auto-hébergement : le Super Admin active les Outils personnalisés pour le compte.

Configuration & essai

Avant de commencer

• Un endpoint HTTPS sur un nom d’hôte public. Chatwoot bloque le HTTP simple, les adresses IP, localhost, les réseaux privés et les adresses .local.

• Le endpoint doit accepter la connexion en moins de 2 secondes et répondre en moins de 20 secondes, avec une réponse de 1 Mo ou moins.

• Ses identifiants, s’il en a besoin.

Créer un outil

1. Allez dans Captain > Outils et cliquez sur Créer un nouvel outil. Utilisez d’abord le sélecteur d’assistant en haut pour choisir l’assistant pour lequel l’outil est destiné. Le formulaire s’ouvre dans un panneau latéral.

   

2. Remplissez :

   • Nom de l’outil : court, par exemple "Recherche de commande" (55 caractères ou moins).

   • Description : quand l’assistant doit l’utiliser, rédigée comme un briefing pour un nouvel agent. Cela détermine si l’assistant choisira cet outil.

   • Méthode : GET pour lire des données ; POST, PUT ou PATCH pour envoyer ou modifier des données ; DELETE pour supprimer quelque chose.

   • URL du endpoint : utilisez {{ parameter_name }} pour les valeurs que l’assistant remplit, par exemple https://api.example.com/orders/``{{ order_id }}.

   • Type d’authentification : Aucun, Bearer Token, Basic Auth ou Clé API (avec Nom de l’en-tête et Valeur de l’en-tête). À utiliser pour les identifiants.

   • En-têtes : cliquez sur Ajouter un en-tête pour les en-têtes fixes dont votre API a besoin à chaque appel, comme une version d’API ou un identifiant de locataire (jusqu’à 16). Les valeurs sont envoyées telles quelles. Chatwoot gère Authorization, Host, Content-Length, Content-Type et tout en-tête commençant par X-Chatwoot lui-même, vous ne pouvez donc pas les ajouter.

   • Paramètres : cliquez sur Ajouter un paramètre pour chaque valeur que l’assistant doit récupérer auprès du client. Donnez un nom, un type, une description, et cochez Requis si nécessaire.

   • Modèle de corps de requête (Optionnel) : pour POST, PUT ou PATCH. Ceci et le modèle de réponse se trouvent sous Modèles. Le modèle de requête est un corps JSON. Prend en charge Liquid, par exemple {{ order_id }} pour un paramètre.

   • Modèle de réponse (Optionnel) : sélectionnez les champs dont l’assistant a besoin, par exemple Commande {{ response.order_id }} statut : {{ response.status }}. Lisez la réponse de l’API via response, par exemple {{ response.status }}. Laissez le modèle vide pour envoyer le JSON brut à Captain.

     

   

3. Cliquez sur Tester la connexion, puis Créer.

   

Tester la connexion ne fonctionne que pour les endpoints sans modèles ni corps de requête. Pour les autres, testez dans le bac à sable. Un résultat vert signifie que votre endpoint a retourné un statut 2xx : il est joignable et a accepté les identifiants.

Testez-le

Posez une question dans le Bac à sable qui nécessite l’outil, par exemple "Où est la commande 1234 ?". Vérifiez que la réponse utilise de vraies données.

Maximisez la valeur

• Les outils personnalisés sont optimaux pour les recherches avec des entrées claires, comme un statut de commande, une réservation ou un enregistrement par ID.

• Chaque assistant peut avoir jusqu’à 50 outils. Gardez néanmoins la liste courte : avec beaucoup d’outils, l’assistant risque de choisir le mauvais.

• Ajouter, modifier, désactiver ou supprimer un outil ne concerne que l’assistant affiché. Les outils qui existaient avant que les outils ne soient spécifiques par assistant ont été copiés pour chaque assistant, vérifiez donc chacun.

• Vous gérez plusieurs assistants ? N’attribuez à chacun que les outils dont il a besoin.

• Désactivez un outil grâce à son interrupteur au lieu de le supprimer. Si un scénario l’utilise, Chatwoot vous avertit d’abord. Voir Définir les garde-fous, lignes directrices et scénarios de Captain.

• Chatwoot envoie des en-têtes à chaque appel afin que votre système connaisse le compte, la conversation, l’e-mail et le téléphone du contact, l’assistant, et si le contact est vérifié. Pour les données privées, vérifiez l’en-tête X-Chatwoot-Contact-Inbox-Verified avant de répondre. Sans validation d’identité, un visiteur peut saisir n’importe quel e-mail dans le widget. Les outils renvoyant uniquement des données publiques n’ont pas besoin de cette vérification. Voir Comment activer la validation d’identité dans Chatwoot ?.

• Si votre API retourne du texte saisi par les clients, ne renvoyez que les champs structurés nécessaires. Captain lit la réponse telle quelle, donc un texte libre peut contenir des instructions qui pourraient être suivies.

Dépannage

Autres causes : Dépanner Captain.