Widget Mintlify

L’assistant répond aux questions sur votre site Mintlify. Pour intégrer la même capacité sur un autre site ou application web, utilisez le widget. Grâce au widget, vous pouvez donner à vos utilisateurs l’accès à un chat IA entraîné sur votre contenu dans le tableau de bord de votre produit, votre site marketing, votre portail d’assistance ou ailleurs.

Ajoutez le widget à n’importe quel site web ou application web à l’aide d’un script hébergé. Le widget possède son propre déclencheur et s’affiche dans un Shadow DOM fermé, ce qui empêche les styles de votre application d’affecter le widget.

La seule option de navigateur requise est l’ID public du widget. Gérez l’état d’activation, les origines autorisées, les pièces jointes, la protection contre les bots et le formulaire de contact de déflection dans votre tableau de bord. Définissez les questions d’introduction spécifiques à l’intégration et une adresse e-mail d’assistance dans la configuration du navigateur.

• Un plan Pro ou Enterprise. Le widget utilise les mêmes crédits que l’assistant.

1. Accédez à la page Widget de votre déploiement.
2. Activez le widget.
3. Ajoutez les origines autorisées où vous intégrez le widget.
4. Copiez l’ID du widget.

Utilisez le playground pour configurer la présentation, les options visuelles et les hooks d’observation de votre widget. Le bloc de code d’installation se met à jour à mesure que vous modifiez chaque option.

Après avoir ajouté le code généré à votre site, rechargez la page. Vérifiez que le déclencheur apparaît, puis cliquez dessus et envoyez une question de test pour confirmer que le widget est connecté.

Définissez defaultOpen sur true pour ouvrir le widget immédiatement après son premier montage :

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  defaultOpen: true,
});

defaultOpen est par défaut à false et ne s’applique qu’à la première initialisation. Appeler à nouveau init() avec le même ID de widget et le même endpoint API ne rouvre pas un widget qu’un visiteur a fermé. Utilisez open() et close() pour le contrôler après l’initialisation.

Attendez init() avant d’appeler d’autres méthodes. Conservez le déclencheur intégré ou ouvrez la présentation configurée depuis n’importe quel bouton de votre application.

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  supportEmail: "hi@mintlify.com",
  starterQuestions: [
    "How do I get started with Mintlify?",
    "How do I customize my docs?",
    "How do I deploy my docs?",
  ],
});

document.querySelector("#help-button").addEventListener("click", () => {
  void window.MintlifyAssistant.open({
    source: "help-button",
    focus: true,
  });
});

Pour ouvrir le widget et envoyer immédiatement une question, appelez ask() :

await window.MintlifyAssistant.ask("How do I authenticate?", {
  source: "authentication-guide",
  open: true,
  focus: true,
});

Les métadonnées d’événement et les requêtes incluent la valeur source, ce qui vous permet de distinguer les interactions intégrées de vos points d’entrée personnalisés.

Utilisez update() pour modifier l’apparence, les libellés, l’e-mail d’assistance, les questions d’introduction ou les hooks sans effacer la conversation en cours. Seuls les champs fournis sont modifiés.

await window.MintlifyAssistant.update({
  appearance: {
    theme: "dark",
    accent: "#7c3aed",
  },
  labels: {
    title: "Docs copilot",
    trigger: "Ask docs",
  },
  supportEmail: "support@example.com",
  starterQuestions: [
    "How do I get started?",
    "How do I manage my account?",
  ],
});

Passez null pour restaurer un champ ou un groupe à sa valeur par défaut, supprimer l’e-mail d’assistance ou restaurer une liste vide de questions d’introduction :

await window.MintlifyAssistant.update({
  appearance: {
    accent: null,
  },
  supportEmail: null,
  starterQuestions: null,
  hooks: null,
});

La modification de identity démarre une nouvelle conversation. La modification de l’ID du widget ou de l’endpoint API nécessite d’appeler destroy() avant un nouveau init().

Vous pouvez fournir supportEmail et starterQuestions lors de l’initialisation et les modifier ultérieurement avec update(). Ces valeurs s’appliquent à l’intégration en cours et ne sont pas héritées de votre tableau de bord Mintlify.

Utilisez filter pour restreindre ce que l’assistant récupère lorsque votre documentation est organisée par langue ou par versions. Omettez un champ pour rechercher dans toutes ses valeurs.

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  filter: {
    language: "en",
    version: "v2",
  },
});

language doit être un code de langue pris en charge, tel que en, es, fr ou zh-Hans. version correspond au nom de la version configurée dans votre tableau de bord.

Modifiez les filtres au moment de l’exécution avec update() lorsque le visiteur change de langue ou de version dans votre application :

await window.MintlifyAssistant.update({
  filter: {
    language: "fr",
    version: null,
  },
});

Passez null sur un champ pour effacer ce filtre, ou filter: null pour effacer les deux.

Passez cet objet à init().

Les substitutions CSS arbitraires et les palettes neutres ne sont pas prises en charge. Le Shadow DOM fermé protège à la fois votre application et le widget des régressions de style entre sites.

hooks: {
  event(event) {
    console.log(event.type, event.actor, event.source);
  },
  error(error) {
    console.error(error.code, error.retryable, error.status);
  },
}

Le hook event reçoit les métadonnées de cycle de vie et d’interaction pour init, open, close, ask, update, reset, navigate et destroy. Les événements n’incluent pas le texte de la question, l’identité, la session ou les jetons CAPTCHA.

Le hook error reçoit un code stable, un booléen retryable et un status HTTP facultatif. Les exceptions levées par l’un ou l’autre des hooks n’interrompent pas le widget.

Passez cet objet facultatif à open().

Passez cet objet facultatif après la chaîne de question dans ask().

Passez cet objet à update(). Chaque champ est facultatif, et null restaure sa valeur par défaut.

Les instantanés de conversation restent privés au widget. Chaque méthode se résout en void.

Si votre site utilise une Content Security Policy, autorisez les origines requises par les fonctionnalités de votre widget activées :

Une politique script-src stricte doit toujours autoriser à la fois le chargeur et le script d’initialisation. Une politique style-src stricte doit autoriser le nonce que vous passez à init(), que le widget copie sur sa feuille de style injectée. Passer nonce à init() ne le propage qu’aux ressources créées par le widget après l’initialisation.