Tutoriel : Créer un assistant de documentation in‑app

Intégrez l’Assistant dans votre application pour répondre aux questions en s’appuyant sur votre documentation.

​

Ce que vous allez créer

Un widget réutilisable qui intègre l’assistant directement dans votre application. Le widget propose :

• Un bouton flottant qui ouvre un panneau de conversation lorsqu’on clique dessus
• Des réponses diffusées en temps réel, basées sur les informations de votre documentation
• Un rendu des messages avec prise en charge de Markdown

Les utilisateurs peuvent utiliser le widget pour obtenir de l’aide sur votre produit sans quitter votre application.

​

Prérequis

• Offre Mintlify Pro ou Enterprise
• Votre nom de domaine, qui apparaît à la fin de l’URL de votre Dashboard. Par exemple, si l’URL de votre Dashboard est https://dashboard.mintlify.com/org-name/domain-name, votre nom de domaine est domain-name
• Une API key de l’Assistant
• Node.js v18 ou version ultérieure et npm installés
• Connaissances de base de React

​

Récupérer votre clé d’API Assistant

1. Accédez à la page API keys de votre Dashboard.
2. Cliquez sur Create Assistant API Key.
3. Copiez la clé d’API Assistant (commence par mint_dsc_) et conservez-la en lieu sûr.

La clé d’API Assistant est un jeton public que vous pouvez utiliser dans le code frontend. Les appels effectués avec ce jeton sont décomptés de l’allocation de messages de votre offre et peuvent entraîner des dépassements.

​

Configurer l’exemple

Clonez le référentiel d’exemple et personnalisez-le selon vos besoins.

1. Cloner le référentiel

   git clone https://github.com/mintlify/assistant-embed-example.git
   cd assistant-embed-example
   
2. Choisir votre outil de développement

   Le référentiel inclut des exemples Next.js et Vite. Choisissez l’outil que vous préférez utiliser.

   Next.js

   cd nextjs
   npm install
   
3. Configurer votre projet

   Ouvrez src/config.js et mettez-le à jour avec les détails de votre projet Mintlify.

   src/config.js

   export const ASSISTANT_CONFIG = {
     domain: 'your-domain',
     docsURL: 'https://yourdocs.mintlify.app',
   };
   

   Remplacez:

   • your-domain par le domain de votre projet Mintlify, visible à la fin de l’URL de votre dashboard.
   • https://yourdocs.mintlify.app par l’URL réelle de votre documentation.
4. Ajouter votre jeton d’API

   Créez un fichier .env à la racine du projet.

   .env

   VITE_MINTLIFY_TOKEN=mint_dsc_your_token_here
   

   Remplacez mint_dsc_your_token_here par votre assistant API key.

5. Démarrer le serveur de développement

   npm run dev
   

   Ouvrez votre application dans un navigateur et cliquez le bouton Ask pour ouvrir le widget de l’assistant.

​

Idées de personnalisation

​

Citations de sources

Extraire et afficher les sources à partir des réponses de l’Assistant :

const extractSources = (parts) => {
  return parts
    ?.filter(p => p.type === 'tool-invocation' && p.toolInvocation?.toolName === 'search')
    .flatMap(p => p.toolInvocation?.result || [])
    .map(source => ({
      url: source.url || source.path,
      title: source.metadata?.title || source.path,
    })) || [];
};

// In your message rendering:
{messages.map((message) => {
  const sources = message.role === 'assistant' ? extractSources(message.parts) : [];
  return (
    <div key={message.id}>
      {/* contenu du message */}
      {sources.length > 0 && (
        <div className="mt-2 text-xs">
          <p className="font-semibold">Sources :</p>
          {sources.map((s, i) => (
            <a key={i} href={s.url} target="_blank" rel="noopener noreferrer" className="text-blue-600">
              {s.title}
            </a>
          ))}
        </div>
      )}
    </div>
  );
})}

​

Suivre les identifiants des fils de conversation

Stockez les identifiants de fil pour conserver l’historique des conversations entre les sessions :

import { useState, useEffect } from 'react';

export function AssistantWidget({ domain, docsURL }) {
  const [threadId, setThreadId] = useState(null);

  useEffect(() => {
    // Récupérer l'ID de fil enregistré depuis localStorage
    const saved = localStorage.getItem('assistant-thread-id');
    if (saved) {
      setThreadId(saved);
    }
  }, []);

  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: `https://api.mintlify.com/discovery/v1/assistant/${domain}/message`,
    headers: {
      'Authorization': `Bearer ${import.meta.env.VITE_MINTLIFY_TOKEN}`,
    },
    body: {
      fp: 'anonymous',
      retrievalPageSize: 5,
      ...(threadId && { threadId }), // Inclure l'ID de fil si disponible
    },
    streamProtocol: 'data',
    sendExtraMessageFields: true,
    fetch: async (url, options) => {
      const response = await fetch(url, options);
      const newThreadId = response.headers.get('x-thread-id');
      if (newThreadId) {
        setThreadId(newThreadId);
        localStorage.setItem('assistant-thread-id', newThreadId);
      }
      return response;
    },
  });

  // ... reste du composant
}

​

Ajouter des raccourcis clavier

Permettez aux utilisateurs d’ouvrir le widget et d’envoyer des messages à l’aide de raccourcis clavier :

useEffect(() => {
  const handleKeyDown = (e) => {
    // Cmd/Ctrl + Shift + I pour afficher/masquer le widget
    if ((e.metaKey || e.ctrlKey) && e.shiftKey && e.key === 'I') {
      e.preventDefault();
      setIsOpen((prev) => !prev);
    }

    // Entrée (lorsque le widget a le focus) pour envoyer
    if (e.key === 'Enter' && !e.shiftKey && document.activeElement.id === 'assistant-input') {
      e.preventDefault();
      handleSubmit();
    }
  };

  window.addEventListener('keydown', handleKeyDown);
  return () => window.removeEventListener('keydown', handleKeyDown);
}, [handleSubmit]);