> ## Documentation Index
> Fetch the complete documentation index at: https://adminroletesting-justin-client-exports.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Crea un assistant dentro de tu aplicación

> Crea e incorpora un asistente de documentación dentro de tu aplicación que responda preguntas con información citada de tu sitio de Mintlify.

<div id="what-you-will-build">
  ## Lo que construirás
</div>

Un widget reutilizable que integra el [assistant](/es/assistant/index) 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.

<Frame>
  <img src="https://mintcdn.com/adminroletesting-justin-client-exports/EkKs8Jdk6h9M5TkU/images/assistant/assistant-embed-demo.gif?s=0372d104bc1455053c9a3613fd390587" alt="Demostración del widget del assistant abriéndose y del usuario escribiendo: How do I get started? Luego el assistant responde." width="800" height="491" data-path="images/assistant/assistant-embed-demo.gif" />
</Frame>

<div id="prerequisites">
  ## Requisitos previos
</div>

* 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](https://dashboard.mintlify.com/settings/organization/api-keys)
* Node.js v18 o superior y npm instalado
* Conocimientos básicos de React

<div id="get-your-assistant-api-key">
  ### Obtén tu clave de API del assistant
</div>

1. Ve a la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard.
2. Haz clic en **Create Assistant API Key**.
3. Copia la clave de API del assistant (comienza con `mint_dsc_`) y guárdala de forma segura.

<Note>
  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.
</Note>

<div id="set-up-the-example">
  ## Configurar el ejemplo
</div>

Clona el [repositorio de ejemplo](https://github.com/mintlify/assistant-embed-example) y personalízalo según tus necesidades.

<Steps>
  <Step title="Clona el repositorio">
    ```bash theme={null}
    git clone https://github.com/mintlify/assistant-embed-example.git
    cd assistant-embed-example
    ```
  </Step>

  <Step title="Elige tu herramienta de desarrollo">
    El repositorio incluye ejemplos con Next.js y Vite. Elige la herramienta que prefieras usar.

    <CodeGroup>
      ```bash title="Next.js" theme={null}
      cd nextjs
      npm install
      ```

      ```bash title="Vite" theme={null}
      cd vite
      npm install
      ```
    </CodeGroup>
  </Step>

  <Step title="Configura tu proyecto">
    Abre `src/config.js` y actualiza los detalles de tu proyecto de Mintlify.

    ```js src/config.js theme={null}
    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.
  </Step>

  <Step title="Agrega tu token de API">
    Crea un archivo `.env` en la raíz del proyecto.

    ```bash .env theme={null}
    VITE_MINTLIFY_TOKEN=mint_dsc_your_token_here
    ```

    Reemplaza `mint_dsc_your_token_here` por tu assistant API key.
  </Step>

  <Step title="Inicia el servidor de desarrollo">
    ```bash theme={null}
    npm run dev
    ```

    Abre tu aplicación en un navegador y haz clic en el botón **Ask** para abrir el widget del assistant.
  </Step>
</Steps>

<div id="customization-ideas">
  ## Ideas para personalizar
</div>

<div id="source-citations">
  ### Citas de fuentes
</div>

Extrae y muestra las fuentes de las respuestas del assistant:

```jsx theme={null}
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>
  );
})}
```

<div id="track-conversation-thread-ids">
  ### Seguimiento de hilos de conversación
</div>

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 se crea 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`.

<Warning>
  Debes almacenar el encabezado `X-Thread-Key` inmediatamente. El servidor solo lo devuelve cuando se crea un nuevo hilo. No puedes recuperarlo más tarde.
</Warning>

```jsx theme={null}
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
}
```

<div id="add-keyboard-shortcuts">
  ### Añadir atajos de teclado
</div>

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

```jsx theme={null}
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]);
```