Embed the AI assistant widget

Install and configure the Mintlify widget to embed an AI assistant trained on your content into any website, web app, or dashboard.

Add the widget to any website or web application with a hosted script. The widget owns its trigger and renders inside a closed Shadow DOM, an isolated document tree that prevents your application styles from affecting the widget.

The only required browser option is the public widget ID. Manage the enabled state, allowed origins, attachments, bot protection, and deflection contact form in your dashboard. Set embed-specific starter questions and a support email in the browser configuration.

• A Pro or Enterprise plan. The widget uses the same credits as the assistant.

1. Navigate to your project's Widget page.
2. Enable the widget.
3. Add allowed origins where you embed the widget.
4. Copy the widget ID.

Use the playground to configure the presentation, visual options, and observer hooks for your widget. The installation code block updates as you change each option.

After you add the generated code to your site, reload the page. Confirm the trigger appears, then click it and send a test question to verify the connection.

Set defaultOpen to true to open the widget immediately after its first mount:

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

defaultOpen defaults to false and only applies to the first initialization. Calling init() again with the same widget ID and API endpoint does not reopen a widget that a visitor closed. Use open() and close() to control it after initialization.

Await init() before calling other methods. Keep the built-in trigger or open the configured presentation from any button in your 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,
  });
});

To open the widget and immediately send a question, call ask():

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

Event metadata and requests include the source value, which lets you distinguish built-in interactions from your custom entry points.

Use update() to change appearance, labels, support email, starter questions, or hooks without clearing the current conversation. Only the supplied fields change.

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?",
  ],
});

Pass null to restore a field or group to its default, remove the support email, or restore an empty starter-question list:

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

Changing identity starts a new conversation. Changing the widget ID or API endpoint requires calling destroy() before a new init().

You can supply supportEmail and starterQuestions during initialization and change them later with update(). These values apply to the current embed and do not inherit from your Mintlify dashboard.

Use filter to restrict what the assistant retrieves when you organize your content by language or versions. Omit a field to search across every value for it.

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

language must be a supported language code, such as en, es, fr, or zh-Hans. version matches the version name configured in your dashboard.

Change filters at runtime with update() when the visitor switches language or version in your application:

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

Pass null on a field to clear that filter, or filter: null to clear both.

Pass this object to init().

The widget does not support arbitrary CSS or neutral-palette overrides. The closed Shadow DOM protects both your application and the widget from cross-site style regressions.

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

The event hook receives lifecycle and interaction metadata for init, open, close, ask, update, reset, navigate, and destroy. Events do not include question text, identity, session, or CAPTCHA tokens.

The error hook receives a stable code, a retryable boolean, and an optional HTTP status. Exceptions thrown by either hook do not interrupt the widget.

Pass this optional object to open().

Pass this optional object after the question string in ask().

Pass this object to update(). Every field is optional, and null restores its default.

Conversation snapshots remain private to the widget. Each method resolves to void.

If your site uses a Content Security Policy, allow the origins required by your enabled widget features:

A strict script-src policy must still authorize both the loader and initialization script. A strict style-src policy must authorize the nonce you pass to init(), which the widget copies to its injected style sheet. Passing nonce to init() propagates it only to resources the widget creates after initialization.

• Assistant
• Mintlify REST API introduction
• AI-native documentation