Skip to main content
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.
  1. 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.
  1. 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.
  1. 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

​
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;
  };
}

​
Suggested Questions

{
  enableSuggestedQuestions?: boolean;       // Optional: Enable/disable question suggestions
  randomlySelectedSuggestedQuestions?: number; // Optional: Number of random questions to show
}

​
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

  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
  1. Performance
  • Enable showAssistantMessageReferences only when citation display is necessary
  • Use randomlySelectedSuggestedQuestions to limit the number of displayed suggestions
  1. 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
  1. 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
  1. 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
  1. Local Storage Issues
  • Implement custom storage functions if needed
  • Clear local storage when testing new configurations
  • Handle storage errors gracefully
  1. Message Reference Display
  • Enable showAssistantMessageReferences for citation display
  • Configure globalReferenceDialog for additional context
  • Handle reference loading states appropriately