diff --git a/docs.json b/docs.json index 8355abedf..2cf4300a9 100644 --- a/docs.json +++ b/docs.json @@ -234,9 +234,10 @@ "icon": "bot", "pages": [ "guides/automate-agent", - "guides/geo", + "guides/assistant-embed", "guides/claude-code", "guides/cursor", + "guides/geo", "guides/windsurf" ] }, diff --git a/guides/assistant-embed.mdx b/guides/assistant-embed.mdx new file mode 100644 index 000000000..e964bff5a --- /dev/null +++ b/guides/assistant-embed.mdx @@ -0,0 +1,281 @@ +--- +title: "Tutorial: Build an in-app documentation assistant" +sidebarTitle: "Build an in-app assistant" +description: "Embed the assistant in your application to answer questions with information from your documentation" +--- + +import { PreviewButton } from "/snippets/previewbutton.jsx" + +## What you will build + +A reusable React component that embeds the [assistant](/ai/assistant) directly in your application. The component provides: + +- A floating widget that opens a chat panel when clicked +- Real-time streaming responses based on information from your documentation + +Users can use the widget to get help with your product without leaving your application. + +Clone the repository to start working with a complete example locally. + +## Prerequisites + +- [Mintlify Pro or Custom plan](https://mintlify.com/pricing) +- Your domain name, which appears at the end of your dashboard URL. For example, if your dashboard URL is `https://dashboard.mintlify.com/org-name/domain-name`, your domain name is `domain-name` +- An [assistant API key](https://dashboard.mintlify.com/settings/organization/api-keys) +- Node.js v18 or higher and npm installed +- Basic React knowledge +- Existing React application (Next.js, Vite, Create React App, or similar). This guide uses a Vite application + +### Get your assistant API key + +1. Navigate to the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard. +2. Click **Create Assistant API Key**. +3. Copy the assistant API key (starts with `mint_dsc_`) and save it securely. + + + The assistant API key is a public token that can be used in frontend code. Calls using this token count toward your plan's message allowance and can incur overages. + + +## Build the widget + + + + +Install the AI SDK for React and a Markdown renderer: + +```bash +npm install ai @ai-sdk/react react-markdown +``` + + + +Create a new file `AssistantWidget.jsx` (or `.tsx` if using TypeScript) in your components directory: + +```jsx AssistantWidget.jsx expandable +import { useChat } from '@ai-sdk/react'; +import { useState } from 'react'; +import ReactMarkdown from 'react-markdown'; + +export function AssistantWidget({ domain }) { + const [isOpen, setIsOpen] = useState(false); + + const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({ + api: `https://api-dsc.mintlify.com/v1/assistant/${domain}/message`, + headers: { + 'Authorization': `Bearer ${process.env.VITE_MINTLIFY_TOKEN}`, + }, + body: { + fp: 'anonymous', + retrievalPageSize: 5, + }, + streamProtocol: 'data', + sendExtraMessageFields: true, + }); + + return ( + <> + + + {isOpen && ( +
+
+

Documentation assistant

+
+ +
+ {messages.map((message) => ( +
+
+ {message.role === 'user' ? ( +
{message.content}
+ ) : ( + {message.content} + )} +
+
+ ))} + + {isLoading &&
Loading...
} +
+ +
+
+ + +
+
+
+ )} + + ); +} +``` + + + + +Add your assistant API token to your `.env` file in your project root: + +```bash .env +VITE_MINTLIFY_TOKEN=mint_dsc_your_token_here +``` + +Restart your development server to apply the changes. + + + Vite requires environment variables to be prefixed with `VITE_`. Use the appropriate prefix for your framework. + + + + + +Import and render the component in your application. Pass your Mintlify project `domain` (the end of your dashboard URL. For example, `domain-name` from `https://dashboard.mintlify.com/org-name/domain-name`). + +```jsx App.jsx +import { AssistantWidget } from './components/AssistantWidget'; + +function App() { + return ( +
+ {/* Your existing app content */} + +
+ ); +} + +export default App; +``` + + + + 1. Start your development server: + ```bash + npm run dev + ``` + 2. Open your application in a browser. + 3. Click the "Ask" button in the bottom-right corner. + 4. Ask a question about your documentation. + + + +## Customization ideas + +This example shows a simple implementation of the assistant API. Here are some ways to begin customizing the widget. + +### Add color customization + +Accept color props and use them for theming: + +```jsx +export function AssistantWidget({ domain, buttonColor = '#2563eb' }) { + // ... rest of component + return ( + <> +