Les outils personnalisés permettent à Captain de solliciter vos API externes pendant les conversations — il peut ainsi vérifier l’état du système, consulter des horaires ou récupérer des données provenant de vos services sans intervention humaine. Lorsqu’un client pose une question, Captain extrait les valeurs pertinentes de la conversation, les insère dans votre requête API, puis utilise la réponse pour formuler sa propre réponse. Les outils personnalisés sont disponibles avec le **forfait Business** et supérieurs. ## Création d’un outil Rendez-vous dans **Captain -> Outils** et cliquez sur **Créer un nouvel outil**. \ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQ1FZM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cb577b7e950815be109f2925cac60ce4b25305ac/CleanShot%202026-04-01%20at%2015.53.06@2x.png) Remplissez les champs suivants : **Nom de l’outil** — Un nom court comme « État du système » ou « Recherche d’horaires » (max 55 caractères). **Description** — Indiquez à Captain quand utiliser cet outil. C’est le champ le plus important. Rédigez-le comme une consigne destinée à un agent de support : « Vérifie l’état actuel du système, incluant les incidents en cours ou la maintenance programmée. » Des descriptions vagues comme « API Statut » feront manquer des occasions d’utiliser l’outil à Captain. **Méthode** — Choisissez GET (pour récupérer des données) ou POST (pour envoyer des données). **URL de l’endpoint** — L’URL de votre API. Utilisez `{{ parameter_name }}` pour insérer les valeurs extraites de la conversation : ``` https://api.yourcompany.com/v1/showtimes?q={{ query }} ``` L’URL doit utiliser HTTPS, doit être un nom d’hôte (pas une adresse IP) et ne peut pas pointer vers localhost ou des réseaux privés. **Authentification** — Choisissez la méthode d’authentification de votre API : \ | Type | Ce que vous fournissez | \ |------|----------------------| \ | Aucune | Pas d’authentification | \ | Bearer Token | Une chaîne de jeton | \ | Basic Auth | Nom d’utilisateur et mot de passe | \ | API Key | Un nom et une valeur d’en-tête personnalisés | Les identifiants d’authentification ne sont visibles que par les administrateurs du compte. \ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRDQ4M1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--dc19f2d14e08901f6921007175ffd5399064a947/CleanShot%202026-04-01%20at%2016.52.41@2x.png) \ **Paramètres** — Définissez ce que Captain doit extraire du message du client. Chaque paramètre nécessite un nom, un type et une description. Par exemple : `query` (Chaîne) — « Le titre du film ou la date demandée par le client. » **Modèle de requête** (POST seulement) — Un modèle de corps JSON utilisant la syntaxe Liquid : ``` { "query": "{{ query }}", "source": "captain" } ``` **Modèle de réponse** — Contrôle ce que Captain voit de la réponse de votre API. Si ce champ est vide, Captain reçoit le JSON brut. Utilisez Liquid pour extraire les champs pertinents : ``` État du système : {{ response.status }}. {{ response.message }} ``` Utilisez `response` pour accéder au corps JSON analysé. Les modèles de réponse aident Captain à se concentrer sur les données pertinentes et à éviter les champs internes comme les ID de base de données ou informations de débogage. ## Tester votre outil Cliquez sur **Tester la connexion** avant de sauvegarder pour vérifier que votre endpoint est accessible. Le test indique le code de statut HTTP. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCREk5M1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--8a952a29edf820a845a1a3ca27072386c225eeef/image.png) Un résultat vert (HTTP 200–299) signifie que la connexion et l’authentification fonctionnent. Notez que le test envoie l’URL sans renseigner les valeurs de paramètre, il vérifie donc uniquement que votre endpoint est accessible et que vos identifiants sont valides. En cas d’échec du test, vérifiez les points suivants : * **401 Non autorisé** — Vos identifiants d’authentification sont incorrects. Vérifiez à nouveau votre token, clé API ou identifiant/mot de passe. * **403 Interdit** — Votre API rejette la requête. Si une vérification d’identité est exigée, sachez que les requêtes de test n’incluent pas d’en-têtes de contact. * **404 Introuvable** — L’URL de l’endpoint est incorrecte. Vérifiez le chemin et assurez-vous que votre API fonctionne. * **Timeout** — Votre API met trop de temps à répondre. Les outils personnalisés ont un délai maximum de 30 secondes ; assurez-vous que votre endpoint répond dans ce laps de temps. ## Contexte envoyé avec chaque appel d’outil Lorsque Captain appelle votre API, il incline des en-têtes de métadonnées pour informer votre backend du contexte : | En-tête | Description | |--------|-------------| | `X-Chatwoot-Account-Id` | ID de votre compte | | `X-Chatwoot-Conversation-Id` | Identifiant de la conversation | | `X-Chatwoot-Contact-Email` | Adresse email du client (si disponible) | | `X-Chatwoot-Contact-Inbox-Verified` | Si l’identité du client est vérifiée HMAC | \ Des en-têtes additionnels incluent `X-Chatwoot-Assistant-Id`, `X-Chatwoot-Tool-Slug`, `X-Chatwoot-Contact-Id`, `X-Chatwoot-Contact-Phone`, et `X-Chatwoot-Conversation-Display-Id`. Vous pouvez utiliser ces en-têtes pour rechercher le client dans votre propre système, enregistrer les conversations qui ont déclenché des appels API, et vérifier l’authenticité des requêtes. ## Sécurité **Protections intégrées :** * Tous les endpoints doivent utiliser HTTPS * Les requêtes vers des plages d’adresses IP privées, localhost et domaines `.local` sont bloquées * Les redirections HTTP ne sont pas suivies * Les réponses sont limitées à 1 Mo * Les identifiants d’authentication ne sont visibles que par les administrateurs **Vérification d’identité :** Si votre outil retourne des données spécifiques au client (commandes, facturation, détails de compte), votre API devrait vérifier l’en-tête `X-Chatwoot-Contact-Inbox-Verified`. Sans la vérification HMAC activée sur votre boîte de réception, un visiteur pourrait fournir n’importe quelle adresse email dans le widget de discussion. Ne retournez des données sensibles que si cet en-tête a la valeur `true`. Pour les outils qui retournent des données publiques (horaires, état du système), cette vérification n’est pas nécessaire. **Injection de prompt :** Si votre API renvoie du contenu généré par les utilisateurs (avis, posts de forum), du texte malveillant pourrait influencer le comportement de Captain. Utilisez les modèles de réponses pour extraire uniquement les champs structurés, et assainissez le contenu côté API. ## Limites | Limite | Valeur | |-------|--------| | Nombre maximal d’outils par compte | 15 | | Recommandé | 10 ou moins (un avertissement apparaît au-dessus de 10) | | Longueur du nom d’outil | 55 caractères | | Taille de la réponse | 1 Mo max | | Délai d’attente | 30 secondes | ## Quand utiliser les outils personnalisés Les outils personnalisés sont particulièrement adaptés aux recherches structurées avec des entrées prévisibles — vérification de l’état du système, récupération d’horaires ou recherche de fiches par ID. Si une intégration dédiée à votre cas d’usage existe déjà dans Chatwoot (par exemple, Shopify pour l’e-commerce), privilégiez cette intégration — elle gérera la recherche, la correspondance approximative, et la synchronisation de données bien plus efficacement qu’un simple appel API. ## Exemples ### Vérification de l’état du système Un outil simple, sans paramètre — Captain l’utilise lorsqu’un client demande si quelque chose est en panne. | Champ | Valeur | |-------|--------| | Nom de l’outil | État du système | | Description | Vérifie l’état opérationnel actuel du système, y compris les incidents en cours ou la maintenance programmée. À utiliser lorsqu’un client signale un problème ou demande si le système est hors service. | | Méthode | GET | | URL de l’endpoint | `https://status.yourcompany.com/api/v1/status` | | Auth | Aucune | | Paramètres | (aucun) | | Modèle de réponse | `État du système : {{ response.status }}. {{ response.message }}` | \ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTVViM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--243c121ad98c746cdbfb6aae317471cc2485ccad/CleanShot%202026-04-01%20at%2015.59.39@2x.png) ### Recherche d’horaires / de séances Pour les entreprises avec des horaires, des plannings ou des listes d’événements — les clients demandent ce qui est disponible et Captain récupère le planning en cours. | Champ | Valeur | |-------|--------| | Nom de l’outil | Recherche d’horaires | | Description | Recherche les horaires de projection de films et les séances. À utiliser lorsqu’un client demande quels films sont à l’affiche ou quand un film spécifique est programmé. | | Méthode | GET | | URL de l’endpoint | `https://api.yourcinema.com/v1/showtimes?q={{ query }}` | | Auth | Bearer Token | | Paramètres | `query` (Chaîne, requis) — « Le titre du film ou la date de séance demandée par le client » | | Modèle de réponse | `{% for show in response.showtimes %}{{ show.title }} — {{ show.date }} à {{ show.time }}{% endfor %}` | \ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCREViM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2a8aaa32f6747f6cdfca6d3abcac3b62bce5060f/image.png) Les outils personnalisés fonctionnent au mieux lorsque les entrées sont simples et la réponse de l’API prévisible — vérifications d’état, recherches et autres requêtes structurées sont des cas d’usage idéaux.