> ## Documentation Index
> Fetch the complete documentation index at: https://rag-docs.peakfs.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Web SDK
> alias: Mercury Assistant SDK for Web
This SDK uses the previous version of RAG Framework as backend. We are working on updating it to the new version.
## Features
The Mercury Assistant SDK provides several key features:
1. **Shadow DOM Technology:**
* Renders HTML elements independently, preserving your app’s design.
* Limitations: Currently, only system fonts are supported.
2. **Chat Window Integration:**
* Embed the chat window in any HTML element as a full-page view, a floating button, or a sidebar, providing flexible integration options.
3. **Chat Behavior Management:**
* The SDK manages the chat session automatically. When a user initiates a conversation, a thread ID is saved in LocalStorage, allowing the chat to persist across sessions.
4. **Proactive Suggestions:**
* Our AI assistant can suggest questions proactively, guiding the conversation and enhancing the user experience. This feature can be disabled through the SDK settings.
## Setup
Before integrating the Mercury Assistant SDK into your web application, you'll need to complete the following steps:
### 1. Request Access
* Contact a member of the innovations team to set up the assistant for your use case
* Find team member contact information in the [Peak Innovations Members directory](https://coda.io/d/Peak-Innovations_d2eP0_r5FYY/Members_su9zN_JI#View-of-Members_tuC2Kh_C)
### 2. Prepare Knowledge Base
* Compile your knowledge base content into PDF files
* Submit these files to the innovations team for processing
* The team will handle the uploading and vectorization of your content
### 3. Obtain Credentials
* Once your knowledge base is processed, you'll receive a unique `appId`
* This `appId` will be used to configure your assistant and access your specific knowledge base
### 4. Begin Integration
* After receiving your `appId`, you can proceed with implementing the SDK
* Follow the configuration guidelines below to customize the assistant for your needs
## Configuration Options
The configuration is stored in one JSON object which you can use to create an assistant, see the `initMercuryChat` here:
```html theme={null}
Document
```
### Basic Configuration
```typescript theme={null}
{
appId: string; // Required: Your unique application identifier
className?: string; // Optional: Additional CSS classes for the container
height?: string; // Optional: Height of the chat window (default: "auto")
width?: string; // Optional: Width of the chat window (default: "auto")
}
```
### Assistant Customization
```typescript theme={null}
{
assistantImage?: string; // Optional: URL for assistant's avatar
assistantHeading?: string; // Optional: Chat window title
assistantDescription?: string; // Optional: Subtitle below the title
assistantMessageIcon?: string; // Optional: Icon shown with assistant messages
}
```
### Greeting Configuration
```typescript theme={null}
{
greetingMessages?: string[]; // Optional: Array of possible greeting messages
streamedGreetingMessage?: { // Optional: Configuration for streaming greeting
message: string;
delay?: number;
};
}
```
### Suggested Questions
```typescript theme={null}
{
enableSuggestedQuestions?: boolean; // Optional: Enable/disable question suggestions
randomlySelectedSuggestedQuestions?: number; // Optional: Number of random questions to show
}
```
### Visual Customization
```typescript theme={null}
{
theme?: {
background: string; // Background color
foreground: string; // Text color
primary: string; // Primary accent color
secondary: string; // Secondary color
muted: string; // Muted elements color
// ... additional theme variables
};
}
```
### Input Field Customization
```typescript theme={null}
{
inputField?: {
placeholder: string; // Placeholder text for input
className: string; // Additional CSS classes
};
sendButton?: {
className: string; // Additional CSS classes for send button
iconDirection: "horizontal" | "vertical"; // Send icon orientation
};
}
```
### References & Citations
```typescript theme={null}
{
showAssistantMessageReferences?: boolean; // Show/hide message references
globalReferenceDialog?: {
title: string;
references: GlobalReference[]; // Array of global references
};
}
```
### Reset Conversation
```typescript theme={null}
{
resetConversationConfig?: {
label?: string; // Reset button label
title?: string; // Confirmation dialog title
description?: string; // Confirmation dialog description
cancelLabel?: string; // Cancel button text
confirmLabel?: string; // Confirm button text
};
}
```
## Implementation Example
```javascript theme={null}
window.initMercuryChat({
containerId: "chat-container",
appId: "your-app-id",
assistantHeading: "Customer Support",
assistantDescription: "24/7 AI Assistant",
enableSuggestedQuestions: true,
theme: {
primary: "222.2 47.4% 11.2%",
background: "0 0% 100%"
},
greetingMessages: ["Hello! How can I help you today?"],
showAssistantMessageReferences: true
});
```
## Storage Management
The SDK automatically manages chat sessions using LocalStorage. You can override this behavior by providing custom storage functions:
```typescript theme={null}
{
getChatId?: () => string | null;
setChatId?: (chatId: string) => void;
}
```
## Best Practices
1. **Responsive Design**
* Always specify either fixed dimensions or responsive values for `height` and `width`
* Use theme variables for consistent styling across different screen sizes
2. **Performance**
* Enable `showAssistantMessageReferences` only when citation display is necessary
* Use `randomlySelectedSuggestedQuestions` to limit the number of displayed suggestions
3. **User Experience**
* Provide clear greeting messages to guide users
* Configure reset conversation options for better session management
* Use appropriate theme colors that match your application's design
4. **Accessibility**
* Ensure sufficient color contrast in theme configuration
* Provide meaningful alt text for assistant and message icons
* Use clear, descriptive labels in the interface
## Common Issues and Solutions
1. **Chat Window Not Appearing**
* Verify that the container ID exists in your HTML
* Check if the appId is correct and active
* Ensure all required configuration options are provided
2. **Styling Conflicts**
* Use the provided `className` option to add custom styles
* Utilize the theme configuration for consistent styling
* Avoid global styles that might affect the chat interface
3. **Local Storage Issues**
* Implement custom storage functions if needed
* Clear local storage when testing new configurations
* Handle storage errors gracefully
4. **Message Reference Display**
* Enable `showAssistantMessageReferences` for citation display
* Configure `globalReferenceDialog` for additional context
* Handle reference loading states appropriately