Les outils personnalisés permettent à Captain d'appeler vos API externes pendant les conversations — il peut ainsi vérifier le statut de garantie, valider la couverture de service ou récupérer des données de vos propres services, sans passer la main à un agent humain.
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 à partir du Forfait Business.
Création d'un outil
Accédez à Captain -> Outils et cliquez sur Créer un nouvel outil.
Remplissez les champs suivants :
Nom de l'outil — Un nom court comme "Vérification de garantie" ou "Zone de service" (max 55 caractères).
Description — Indiquez à Captain quand utiliser cet outil. Il s'agit du champ le plus important. Rédigez-le comme si vous briefiez un agent de support : "Vérifie le statut de garantie d’un produit à partir de son numéro de série." Des descriptions vagues comme "API Garantie" feront passer Captain à côté d'occasions d'utiliser l’outil.
Méthode — Choisissez GET (pour récupérer des données) ou POST (pour soumettre 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/warranty/{{ serial_number }}
L’URL doit utiliser HTTPS, doit être un nom d’hôte (pas une adresse IP) et ne peut pas pointer vers localhost ni des réseaux privés.
Authentification — Choisissez la méthode d'authentification utilisée par votre API :
-
Aucune — Pas d’authentification
-
Jeton Bearer — Envoie votre jeton dans l’en-tête
Authorization -
Authentification basique — Envoie un nom d’utilisateur et un mot de passe
-
Clé API — Envoie un nom et une valeur d’en-tête personnalisés (par ex.
X-API-Key)
Les identifiants d’authentification sont uniquement visibles par les administrateurs du compte.
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 : serial_number (Chaîne) — "Le numéro de série du produit, situé au dos de l’appareil."
Modèle de requête (POST uniquement) — Un modèle de corps JSON utilisant la syntaxe Liquid.
Modèle de réponse — Contrôle ce que Captain voit à partir de la réponse de votre API. S’il est laissé vide, Captain reçoit le JSON brut.
Utilisez Liquid pour extraire les champs pertinents. Par exemple : Série {{ response.serial_number }} : {{ response.warranty_status }}. Expire le : {{ response.expiry_date }}.
Utilisez response pour accéder au corps JSON analysé. Les modèles de réponse aident Captain à se concentrer sur les données importantes et à éviter les champs internes comme les identifiants de base de données ou les informations de debug.
Tester votre outil
Cliquez sur Tester la connexion avant d’enregistrer pour vérifier que votre endpoint est accessible. Le test affiche le code de statut HTTP.
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 des paramètres, il vérifie donc uniquement que votre endpoint est accessible et que vos identifiants sont acceptés.
Si le test échoue, vérifiez les éléments suivants :
-
401 Non autorisé — Vos identifiants d’authentification sont incorrects. Vérifiez votre jeton bearer, votre clé API ou votre nom d’utilisateur/mot de passe.
-
403 Interdit — Votre API rejette la requête. Si vous exigez une vérification d’identité, sachez que les requêtes de test n’incluent pas les en-têtes de contact.
-
404 Introuvable — L’URL du endpoint est incorrecte. Vérifiez le chemin et assurez-vous que votre API est en ligne.
-
Délai dépassé — Votre API a mis trop de temps à répondre. Les outils personnalisés ont un délai d’attente maximum de 30 secondes ; assurez-vous que votre endpoint répond dans ce laps de temps.
Contexte envoyé à chaque appel d’outil
Lorsque Captain appelle votre API, il inclut des en-têtes de métadonnées pour que votre back-end connaisse le contexte :
-
X-Chatwoot-Account-Id— ID de votre compte -
X-Chatwoot-Conversation-Id— ID de la conversation -
X-Chatwoot-Contact-Email— Email du client (si disponible) -
X-Chatwoot-Contact-Inbox-Verified— Si l’identité du client est vérifiée par HMAC -
X-Chatwoot-Assistant-Id— L’ID de l’assistant Captain qui initie l’appel -
X-Chatwoot-Tool-Slug— L’identifiant interne de l’outil -
X-Chatwoot-Contact-Id— ID du contact client -
X-Chatwoot-Contact-Phone— Numéro de téléphone du client (si disponible) -
X-Chatwoot-Conversation-Display-Id— Numéro d’affichage de la conversation
Vous pouvez utiliser ces en-têtes pour rechercher le client dans votre propre système, enregistrer quelles conversations 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’IP privées, localhost et les domaines
.localsont bloquées -
Les redirections HTTP ne sont pas suivies
-
Les réponses sont limitées à 1 Mo
-
Les identifiants d’authentification ne sont visibles que par les administrateurs
Vérification de l’identité : Si votre outil renvoie des données spécifiques à un client (commandes, facturation, détails de compte), votre API doit vérifier l’en-tête X-Chatwoot-Contact-Inbox-Verified. Sans vérification HMAC activée sur votre boîte de réception, un visiteur pourrait renseigner n’importe quelle adresse e-mail dans le widget de chat. Ne retournez des données sensibles que lorsque cet en-tête est à true. Pour les outils retournant des données publiques, ce contrôle n’est pas nécessaire.
Injection d'invite : Si votre API renvoie du contenu généré par l'utilisateur (avis, messages de forum), un texte malveillant pourrait influencer le comportement de Captain. Utilisez les modèles de réponse pour extraire uniquement des champs structurés, et nettoyez les contenus côté API.
Limites
-
Nombre maximal d’outils par compte — 15
-
Recommandé — 10 ou moins. Un avertissement apparaît au-dessus de 10 ; plus d’outils compliquent la sélection du bon outil par Captain.
-
Longueur du nom de l’outil — 55 caractères
-
Taille de la réponse — 1 Mo max
-
Délai d’attente des requêtes — 30 secondes
Quand utiliser des outils personnalisés
Les outils personnalisés conviennent particulièrement aux recherches structurées avec des entrées prévisibles — vérification du statut système, récupération de plannings ou consultation de dossiers via un identifiant. Si vous disposez déjà d’une intégration dédiée pour votre cas d’usage (par exemple Shopify pour le e-commerce), privilégiez cette solution : les intégrations dédiées gèrent la recherche, la correspondance approximative, et la synchronisation des données de manière plus fiable qu’un simple appel d’API.
Exemples
Recherche de garantie
Lorsqu’un client demande si son produit est toujours sous garantie, Captain peut le vérifier via le numéro de série.
-
Nom de l’outil : Vérification de garantie
-
Description : Vérifie le statut de garantie d’un produit à partir de son numéro de série. À utiliser lorsqu’un client demande si son produit est couvert, à quelle date la garantie expire, ou quel type de couverture il possède.
Vérification de la zone de service
Pour les entreprises opérant dans certaines régions — les clients demandent si un service est disponible à leur emplacement.
-
Nom de l’outil : Vérification de la zone de service
-
Description : Vérifie si le service ou la livraison est disponible dans une zone spécifique via le code postal ou le nom de la ville du client.
Les outils personnalisés fonctionnent le mieux lorsque les entrées sont simples et la réponse API prévisible — pour les vérifications de statut, recherches et autres requêtes structurées, c’est l’idéal.