Connecter des outils personnalisés

Connectez GitBook Assistant à n’importe quel outil appelable depuis votre application — en particulier les flux de support

Les outils personnalisés permettent à l’Assistant GitBook, dans le l’intégration Docs d’effectuer de véritables actions.

Vous pouvez le connecter à n’importe quel outil auquel votre application peut accéder. Cela inclut vos API backend, les SDK tiers et les systèmes internes.

Si votre application peut l’appeler, l’Assistant peut l’appeler.

Exemples courants :

• Créer ou mettre à jour des tickets d’assistance au nom de l’utilisateur

• Passer à l’assistance en ouvrant un chat de support avec un message prérempli

  Transfert vers l’assistance est un excellent moyen de commencer avec les outils personnalisés. C’est la façon la plus rapide de débloquer les utilisateurs.

• Déclencher des actions produit (réinitialiser le MFA, renvoyer une invitation, activer un flag de fonctionnalité)

• Consulter l’état du compte dans votre backend

• Lancer des workflows dans des outils comme Jira, Linear, Slack ou Zendesk

En plus des outils que vous définissez dans la configuration de l’embed, l’Assistant peut également utiliser n’importe quel serveurs MCP que vous configurez dans Paramètres → IA et MCP.

Où les outils s’exécutent

La fonction execute de l’outil s’exécute dans le même environnement que votre intégration d’embed.

Cela signifie généralement qu’elle s’exécute dans le navigateur de l’utilisateur, à l’intérieur de votre application.

Vous pouvez donc :

• Appeler vos propres points de terminaison backend

• Appeler n’importe quel SDK tiers déjà chargé dans votre application (par exemple, Intercom)

• Ouvrir des modales, des liens profonds ou des interfaces intégrées au produit

Évitez de mettre des secrets dans le code côté client — appelez plutôt votre backend.

Ajouter un outil

Définir des outils :

• Via window.GitBook("configure", …) pour l’implémentation balise script implémentation

• Via la tools prop pour le Node.js/NPM package et les composants React

Les outils ne sont pas la même chose que l’embed actions.

• Utiliser actions pour les boutons sur lesquels l’utilisateur clique.

• Utilisez des outils lorsque vous voulez que l’Assistant choisisse et exécute du code.

Modèle d’outil (renvoyer un e-mail d’invitation)

Examinons un exemple :

window.GitBook("configure", {
  tools: [
    {
      // Enregistrer l’outil avec un nom et une description.
      name: "resend_invite",
      description:
        "Renvoyer un e-mail d’invitation lorsque l’utilisateur ne le trouve pas ou indique qu’il a expiré.",

      // Le schéma d’entrée est une donnée accessible dans la fonction execute.
      inputSchema: {
        type: "object",
        properties: {
          email: {
            type: "string",
            description:
              "L’adresse e-mail à laquelle renvoyer l’invitation. Si elle est inconnue, demandez d’abord à l’utilisateur.",
          },
        },
        required: ["email"],
      },

      // Un bouton de confirmation facultatif affiché avant l’exécution de la fonction execute.
      confirmation: { icon: "paper-plane", label: "Renvoyer l’invitation ?" },

      // La fonction execute est la fonction qui sera appelée lorsque l’outil est utilisé.
      execute: async (input) => {
        const { email } = input;

        const result = await fetch("/api/invites/resend", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ email }),
        }).then((r) => r.json());

        return {
          // La sortie est renvoyée à l’IA.
          output: {
            recipient: email,
            status: result.status ?? "success",
          },
          // Le résumé est affiché à l’utilisateur.
          summary: {
            icon: "check",
            text: "Invitation renvoyée.",
          },
        };
      },
    },
  ],
});

Comment les outils sont utilisés

Une fois que vous avez enregistré des outils, l’Assistant peut les choisir automatiquement — en fonction de la question de l’utilisateur et de votre outil description.

Si des champs obligatoires manquent, l’Assistant doit poser des questions de suivi.

Si vous ajoutez confirmation, l’utilisateur doit approuver avant l’exécution de l’outil.

Champs de l’outil

• name: Identifiant unique.

• description: L’indication « quand utiliser ceci » pour l’Assistant.

• inputSchema: Schéma JSON pour les entrées de l’outil.

• confirmation (facultatif) : Un bouton de confirmation affiché avant l’exécution de l’outil.

• execute(input): Fonction asynchrone qui exécute l’action.

  • Retourner { output, summary }.

  • output est renvoyé à l’Assistant.

  • summary est affiché à l’utilisateur.

Confirmation

Utiliser confirmation quand vous voulez que l’utilisateur approuve une action. Cela aide à éviter des effets secondaires inattendus.

confirmation accepte :

• label (obligatoire) : Texte du bouton.

• icon (facultatif) : Un Font Awesome nom d’icône.

Workflow de support

Le support est le cas d’usage le plus intéressant pour les outils.

Vous pouvez laisser l’Assistant :

• Collecter les détails manquants

• Créer un ticket dans votre système

• Ouvrir un canal de support humain avec le contexte prérempli

Modèle : ouvrir un chat d’assistance avec un message prérempli

Utilisez ceci lorsque vous voulez un transfert propre vers un humain.

window.GitBook("configure", {
  tools: [
    {
      name: "open_support_chat",
      description:
        "Ouvrir le chat d’assistance avec un message prérempli afin que l’utilisateur puisse contacter rapidement le support.",
      inputSchema: {
        type: "object",
        properties: {
          message: {
            type: "string",
            description:
              "Le message à envoyer au support. S’il manque, demandez d’abord à l’utilisateur.",
          },
        },
      },
      confirmation: { icon: "circle-question", label: "Ouvrir le chat d’assistance" },
      execute: (input) => {
        // Fermer l’Assistant GitBook
        window.GitBook('close');
     
        // Exemples :
        // - Intercom : Intercom('showNewMessage', input.message);
        // - Zendesk : zE('messenger', 'open');
        
        return {
          output: {
            status: "success",
          },
          summary: { icon: 'check', text: "Transféré vers le support." },
        };
      },
    },
  ],
});

Associez cela à une action toujours visible Contacter le support dans la barre latérale de l’embed. Vous pouvez configurer les actions en suivant Personnalisation de l’Embed.

Étapes suivantes

• Besoin de l’ensemble complet de l’API d’embed ? Consultez Référence de l’API.

• Vous voulez plus de contrôles d’interface (message d’accueil, suggestions, actions) ? Consultez Personnalisation de l’Embed.