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, plutôt que de passer le relais.

Offre et accès : Business ou Enterprise (Tarifs et offres). Avec Startups, Outils affiche généralement Passez à une offre supérieure 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. Hébergement autonome : le Super Admin active Outils personnalisés pour le compte.

Configurer et essayer

Avant de commencer

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

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

• Ses identifiants, s’il en nécessite.

Créer un outil

1. Accédez à Captain > Outils et cliquez sur Créer un nouvel outil. Commencez par utiliser le sélecteur d’assistant en haut pour choisir l’assistant auquel l’outil est destiné. Le formulaire s’ouvre dans un panneau latéral.

   

2. Renseignez les champs suivants :

   • Nom de l’outil : un nom court, par exemple « Recherche de commande » (55 caractères maximum).

   • Description : indiquez quand l’assistant doit l’utiliser, sous la forme d’un briefing destiné à un nouvel agent. C’est ce qui détermine si l’assistant sélectionne l’outil.

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

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

   • Type d’authentification : Aucune, Jeton Bearer, Authentification de base ou Clé API (avec Nom de l’en-tête et Valeur de l’en-tête). Utilisez cette option pour les identifiants.

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

   • Paramètres : cliquez sur Ajouter un paramètre pour chaque valeur que l’assistant doit demander au client. Indiquez un nom, un type et une description, et cochez Obligatoire si nécessaire.

   • Ajouter une adresse e-mail vérifiée : ajoute un paramètre. Chatwoot y place l’adresse e-mail que le client a vérifiée à l’aide d’un code à usage unique. Dans les conversations avec les clients, Captain ne peut ni la voir ni la modifier. Utilisez ce paramètre lorsque votre API recherche le client par adresse e-mail, par exemple https://api.example.com/orders?email={{ email }}. Un outil peut avoir un seul paramètre d’adresse e-mail vérifiée.

   • Exiger la vérification de l’adresse e-mail : Captain ne peut utiliser l’outil qu’après que le client a vérifié son adresse e-mail à l’aide d’un code à usage unique. Si l’outil comporte un paramètre d’adresse e-mail vérifiée, ce réglage est toujours activé.

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

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

     

   

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

   

Tester la connexion fonctionne uniquement pour les points de terminaison sans modèles ni corps de requête. Pour les autres, effectuez le test dans le Playground. Un résultat vert signifie que votre point de terminaison a renvoyé un statut 2xx : il est accessible et a accepté les identifiants.

Tester l’outil

Posez dans le Playground une question qui nécessite l’outil, par exemple « Où est la commande 1234 ? ». Vérifiez que la réponse utilise des données réelles.

Protéger les données des clients

Un client peut saisir n’importe quelle adresse e-mail dans le widget ou le formulaire préalable à la conversation. Certains outils renvoient ou modifient les données d’un client, comme des commandes, des factures ou des réservations. Activez la vérification de l’adresse e-mail pour ces outils.

Lorsque Captain appelle l’un de ces outils, il demande son adresse e-mail au client. Chatwoot envoie un code à 6 chiffres à cette adresse, que le client saisit dans la conversation. L’outil ne s’exécute qu’après que Chatwoot a vérifié que le code est correct.

• La vérification ne s’applique qu’à une seule conversation. Elle dure jusqu’à 1 heure, ou jusqu’à 3 heures dans les conversations par e-mail. Une nouvelle conversation commence sans vérification.

• Un code expire au bout de 30 minutes. Le client peut essayer un code 5 fois. Chatwoot envoie au maximum 5 codes à un client par heure.

• Exiger la vérification de l’adresse e-mail ne détermine pas l’adresse e-mail à laquelle l’outil envoie sa requête. Si votre API reçoit l’adresse e-mail dans un paramètre ordinaire, Captain peut envoyer n’importe quelle adresse. Pour que l’outil n’envoie que l’adresse e-mail vérifiée, utilisez Ajouter une adresse e-mail vérifiée.

• Chatwoot peut détecter qu’un outil utilise des données client. Si c’est le cas et que l’outil n’exige pas de vérification de l’adresse e-mail, Chatwoot affiche Enregistrer sans vérification de l’adresse e-mail ? avant l’enregistrement. Cliquez sur Retour ou Enregistrer quand même.

• Dans le Playground et dans les suggestions de réponse, l’utilisateur est un membre de l’équipe. Captain renseigne le paramètre d’adresse e-mail vérifiée. Le résultat vous indique si Chatwoot a vérifié cette adresse e-mail.

• Pour les ensembles d’outils installés, les administrateurs peuvent activer ou désactiver Exiger la vérification de l’adresse e-mail.

Tirer le meilleur parti de l’outil

• Les outils personnalisés sont particulièrement adaptés aux recherches avec des entrées précises, comme le statut d’une commande, une réservation ou un enregistrement par ID.

• Chaque assistant peut avoir jusqu’à 50 outils. Gardez tout de même une liste courte : plus il y a d’outils, plus l’assistant risque de choisir le mauvais.

• L’ajout, la modification, la désactivation ou la suppression d’un outil ne concerne que l’assistant que vous consultez. Les outils créés avant qu’ils ne soient propres à chaque assistant ont été copiés vers tous les assistants ; vérifiez donc chacun d’eux.

• Vous utilisez plusieurs assistants ? Attribuez à chacun uniquement les outils dont il a besoin.

• Désactivez un outil à l’aide de son bouton plutôt que de le supprimer. Si un scénario l’utilise, Chatwoot vous avertit au préalable. Consultez Définir les garde-fous, les consignes et les scénarios de Captain.

• Chatwoot envoie des en-têtes avec chaque requête. Ils indiquent à votre système le compte, la conversation, le contact, l’assistant et la boîte de réception.

  • X-Chatwoot-Verified-Email contient l’adresse e-mail que le client a vérifiée à l’aide d’un code à usage unique. Si le client n’a pas effectué la vérification, Chatwoot n’envoie pas cet en-tête.

  • X-Chatwoot-Contact-Email contient l’adresse e-mail enregistrée dans la fiche du contact. N’importe qui peut saisir cette adresse. Ne l’utilisez pas pour renvoyer des données privées.

  • X-Chatwoot-Contact-Inbox-Verified vaut true lorsque la validation de l’identité (HMAC) a vérifié le contact. Cet en-tête ne vérifie pas l’adresse e-mail.

  Si votre système renvoie des données privées, vérifiez X-Chatwoot-Verified-Email ou activez la vérification de l’adresse e-mail pour l’outil. Consultez Comment activer la validation de l’identité dans Chatwoot ?.

• Si votre API renvoie du texte rédigé par des clients, ne renvoyez que les champs structurés dont vous avez besoin. Captain lit la réponse telle quelle ; le texte libre peut donc contenir des instructions qu’il pourrait suivre.

Dépannage

Pour connaître d’autres causes, consultez Dépanner Captain.