Web SDK - Peak RAG Framework

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:

Shadow DOM Technology:

Renders HTML elements independently, preserving your app’s design.
Limitations: Currently, only system fonts are supported.

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.

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.

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

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:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
    <script src="https://mercuryassistant.blob.core.windows.net/mercury-assistant-sdk/mercury-assistant-latest.js"></script>
    <link rel="stylesheet" href="https://mercuryassistant.blob.core.windows.net/mercury-assistant-sdk/mercury-assistant-css-latest.css" />
  </head>
  <body>
    <div id="mercury-container"></div>
    <script>
      initMercuryChat({
        containerId: "mercury-container",
        appId: "your-app-id-here",
        assistantHeading: "Mercury Assistant",
        assistantDescription: "Powered by Peak",
        enableSuggestedQuestions: true,
        showAssistantMessageReferences: true,
        assistantImage: "https://emojiisland.com/cdn/shop/products/Robot_Emoji_Icon_7070a254-26f7-4a54-8131-560e38e34c2e_grande.png?v=1571606114",
        height: "700px",
      });
    </script>
  </body>
</html>

Basic Configuration

{
  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

{
  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

{
  greetingMessages?: string[];      // Optional: Array of possible greeting messages
  streamedGreetingMessage?: {       // Optional: Configuration for streaming greeting
    message: string;
    delay?: number;
  };
}

Visual Customization

{
  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

{
  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

{
  showAssistantMessageReferences?: boolean;  // Show/hide message references
  globalReferenceDialog?: {
    title: string;
    references: GlobalReference[];          // Array of global references
  };
}

Reset Conversation

{
  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

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:

{
  getChatId?: () => string | null;
  setChatId?: (chatId: string) => void;
}

Best Practices

Responsive Design

Always specify either fixed dimensions or responsive values for height and width
Use theme variables for consistent styling across different screen sizes

Performance

Enable showAssistantMessageReferences only when citation display is necessary
Use randomlySelectedSuggestedQuestions to limit the number of displayed suggestions

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

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

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

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

Local Storage Issues

Implement custom storage functions if needed
Clear local storage when testing new configurations
Handle storage errors gracefully

Message Reference Display

Enable showAssistantMessageReferences for citation display
Configure globalReferenceDialog for additional context
Handle reference loading states appropriately

​Features

​Setup

​1. Request Access

​2. Prepare Knowledge Base

​3. Obtain Credentials

​4. Begin Integration

​Configuration Options

​Basic Configuration

​Assistant Customization

​Greeting Configuration

​Suggested Questions

​Visual Customization

​Input Field Customization

​References & Citations

​Reset Conversation

​Implementation Example

​Storage Management

​Best Practices

​Common Issues and Solutions

Features

Setup

1. Request Access

2. Prepare Knowledge Base

3. Obtain Credentials

4. Begin Integration

Configuration Options

Basic Configuration

Assistant Customization

Greeting Configuration

Suggested Questions

Visual Customization

Input Field Customization

References & Citations

Reset Conversation

Implementation Example

Storage Management

Best Practices

Common Issues and Solutions