Widget de Mintlify

El asistente responde preguntas en tu sitio de Mintlify. Para incrustar la misma capacidad en otro sitio o aplicación web, usa el widget. Con el widget, puedes ofrecer a tus usuarios acceso a un chat de IA entrenado con tu contenido en el panel de tu producto, sitio de marketing, portal de soporte u otros lugares.

Añade el widget a cualquier sitio web o aplicación web con un script alojado. El widget gestiona su propio activador y se renderiza dentro de un Shadow DOM cerrado, lo que evita que los estilos de tu aplicación afecten al widget.

La única opción de navegador obligatoria es el ID público del widget. Gestiona el estado de activación, los orígenes permitidos, los adjuntos, la protección contra bots y el formulario de contacto de deflection desde tu panel. Configura las preguntas iniciales específicas del embed y un correo electrónico de soporte en la configuración del navegador.

• Un plan Pro o Enterprise. El widget usa los mismos créditos que el asistente.

1. Ve a la página Widget de tu despliegue.
2. Activa el widget.
3. Añade los orígenes permitidos donde vas a incrustar el widget.
4. Copia el ID del widget.

Usa el playground para configurar la presentación, las opciones visuales y los hooks de observación de tu widget. El bloque de código de instalación se actualiza a medida que cambias cada opción.

Después de añadir el código generado a tu sitio, recarga la página. Confirma que aparece el activador y, luego, haz clic en él y envía una pregunta de prueba para verificar que el widget está conectado.

Establece defaultOpen en true para abrir el widget inmediatamente después de su primer montaje:

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

defaultOpen es false por defecto y solo se aplica a la primera inicialización. Llamar a init() de nuevo con el mismo ID de widget y endpoint de API no vuelve a abrir un widget que un visitante haya cerrado. Usa open() y close() para controlarlo después de la inicialización.

Espera a init() antes de llamar a otros métodos. Mantén el activador integrado o abre la presentación configurada desde cualquier botón de tu aplicación.

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  supportEmail: "[email protected]",
  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,
  });
});

Para abrir el widget y enviar inmediatamente una pregunta, llama a ask():

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

Los metadatos de eventos y las solicitudes incluyen el valor source, que te permite distinguir las interacciones integradas de tus puntos de entrada personalizados.

Usa update() para cambiar la apariencia, las etiquetas, el correo de soporte, las preguntas iniciales o los hooks sin borrar la conversación actual. Solo se cambian los campos proporcionados.

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

Pasa null para restaurar un campo o grupo a su valor por defecto, eliminar el correo de soporte o restaurar una lista vacía de preguntas iniciales:

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

Cambiar identity inicia una nueva conversación. Cambiar el ID del widget o el endpoint de la API requiere llamar a destroy() antes de un nuevo init().

Puedes proporcionar supportEmail y starterQuestions durante la inicialización y cambiarlos más tarde con update(). Estos valores se aplican al embed actual y no se heredan desde tu panel de Mintlify.

Usa filter para restringir lo que el asistente recupera cuando tu documentación está organizada por idioma o versiones. Omite un campo para buscar en todos sus valores.

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

language debe ser un código de idioma admitido, como en, es, fr o zh-Hans. version coincide con el nombre de la versión configurada en tu panel.

Cambia los filtros en tiempo de ejecución con update() cuando el visitante cambie de idioma o versión en tu aplicación:

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

Pasa null en un campo para borrar ese filtro, o filter: null para borrar ambos.

Pasa este objeto a init().

No se admiten sobrescrituras arbitrarias de CSS ni de paleta neutra. El Shadow DOM cerrado protege tanto a tu aplicación como al widget de regresiones de estilos entre sitios.

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

El hook event recibe metadatos de ciclo de vida e interacción para init, open, close, ask, update, reset, navigate y destroy. Los eventos no incluyen el texto de la pregunta, la identidad, la sesión ni los tokens CAPTCHA.

El hook error recibe un code estable, un booleano retryable y un status HTTP opcional. Las excepciones lanzadas por cualquiera de los hooks no interrumpen el widget.

Pasa este objeto opcional a open().

Pasa este objeto opcional después de la cadena de la pregunta en ask().

Pasa este objeto a update(). Todos los campos son opcionales y null restaura su valor por defecto.

Las capturas de conversación permanecen privadas al widget. Cada método se resuelve en void.

Si tu sitio usa una Content Security Policy, permite los orígenes requeridos por las funciones habilitadas de tu widget:

Una política script-src estricta debe autorizar tanto el cargador como el script de inicialización. Una política style-src estricta debe autorizar el nonce que pasas a init(), que el widget copia a su hoja de estilos inyectada. Pasar nonce a init() lo propaga solo a los recursos que el widget crea después de la inicialización.