Crea un assistant dentro de tu aplicación

Lo que construirás

Un widget reutilizable que integra el assistant directamente en tu aplicación. El widget ofrece:

Un botón flotante que abre un panel de chat al hacer clic
Respuestas en tiempo real transmitidas a partir de la información de tu documentación
Visualización de mensajes con compatibilidad con Markdown

Los usuarios pueden usar el widget para obtener ayuda con tu producto sin salir de tu aplicación.

Demostración del widget del assistant abriéndose y del usuario escribiendo: How do I get started? Luego el assistant responde.

Requisitos previos

El assistant de Mintlify habilitado
Tu domain, que aparece al final de la URL de tu dashboard. Por ejemplo, si la URL de tu dashboard es https://dashboard.mintlify.com/org-name/domain-name, tu domain es domain-name
Una assistant API key
Node.js v18 o superior y npm instalado
Conocimientos básicos de React

Obtén tu clave de API del assistant

Ve a la página de API keys en tu dashboard.
Haz clic en Create Assistant API Key.
Copia la clave de API del assistant (comienza con mint_dsc_) y guárdala de forma segura.

La clave de API del assistant es un token público que puedes usar en el código del frontend. Las llamadas que usen este token se contabilizan en la cuota de mensajes de tu plan y pueden generar cargos por excedente.

Configurar el ejemplo

Clona el repositorio de ejemplo y personalízalo según tus necesidades.

Clona el repositorio

git clone https://github.com/mintlify/assistant-embed-example.git
cd assistant-embed-example

Elige tu herramienta de desarrollo

El repositorio incluye ejemplos con Next.js y Vite. Elige la herramienta que prefieras usar.

cd nextjs
npm install

cd vite
npm install

Configura tu proyecto

Abre src/config.js y actualiza los detalles de tu proyecto de Mintlify.

src/config.js

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

Reemplaza:

your-domain por el domain de tu proyecto de Mintlify que encontrarás al final de la URL de tu dashboard.
https://yourdocs.mintlify.site por la URL real de tu documentación.

Agrega tu token de API

Crea un archivo .env en la raíz del proyecto.

.env

VITE_MINTLIFY_TOKEN=mint_dsc_your_token_here

Reemplaza mint_dsc_your_token_here por tu assistant API key.

Inicia el servidor de desarrollo

npm run dev

Abre tu aplicación en un navegador y haz clic en el botón Ask para abrir el widget del assistant.

Ideas para personalizar

Citas de fuentes

Extrae y muestra las fuentes de las respuestas del 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}>
      {/* contenido del mensaje */}
      {sources.length > 0 && (
        <div className="mt-2 text-xs">
          <p className="font-semibold">Fuentes:</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>
  );
})}

Seguimiento de hilos de conversación

Almacena los IDs de hilo y las claves de hilo para mantener el historial de conversación entre sesiones. Cuando un usuario crea un nuevo hilo de conversación, el servidor devuelve dos valores en los encabezados de la respuesta:

X-Thread-Id: El identificador del hilo
X-Thread-Key: Una clave secreta para el hilo (solo se devuelve una vez, cuando creas el hilo)

Debes capturar y persistir ambos valores en la primera respuesta. En cada mensaje posterior, incluye tanto threadId como threadKey en el cuerpo de la solicitud. Si envías un threadId sin el threadKey correspondiente, el servidor devuelve un error 404.

Debes almacenar el encabezado X-Thread-Key inmediatamente. El servidor solo lo devuelve cuando creas un nuevo hilo. No puedes recuperarlo más tarde.

import { useState, useEffect } from 'react';

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

  useEffect(() => {
    // Recuperar el ID y la clave del hilo guardados desde localStorage
    const savedId = localStorage.getItem('assistant-thread-id');
    const savedKey = localStorage.getItem('assistant-thread-key');
    if (savedId && savedKey) {
      setThreadId(savedId);
      setThreadKey(savedKey);
    }
  }, []);

  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 }),
      ...(threadKey && { threadKey }),
    },
    streamProtocol: 'data',
    sendExtraMessageFields: true,
    fetch: async (url, options) => {
      const response = await fetch(url, options);
      const newThreadId = response.headers.get('x-thread-id');
      const newThreadKey = response.headers.get('x-thread-key');
      if (newThreadId) {
        setThreadId(newThreadId);
        localStorage.setItem('assistant-thread-id', newThreadId);
      }
      if (newThreadKey) {
        setThreadKey(newThreadKey);
        localStorage.setItem('assistant-thread-key', newThreadKey);
      }
      return response;
    },
  });

  // ... resto del componente
}

Añadir atajos de teclado

Permite que los usuarios abran el widget y envíen mensajes mediante atajos de teclado:

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

    // Enter (cuando el widget tiene el foco) para enviar
    if (e.key === 'Enter' && !e.shiftKey && document.activeElement.id === 'assistant-input') {
      e.preventDefault();
      handleSubmit();
    }
  };

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

​Lo que construirás

​Requisitos previos

​Obtén tu clave de API del assistant

​Configurar el ejemplo

​Ideas para personalizar

​Citas de fuentes

​Seguimiento de hilos de conversación

​Añadir atajos de teclado

Lo que construirás

Requisitos previos

Obtén tu clave de API del assistant

Configurar el ejemplo

Ideas para personalizar

Citas de fuentes

Seguimiento de hilos de conversación

Añadir atajos de teclado