Configuration Overview

The SiteAssist widget is highly customizable through configuration options passed to the init method. This guide covers all available options and how to use them.

Basic Configuration

The minimal configuration requires only an API key:

SiteAssist("init", {
  apiKey: "YOUR_API_KEY_HERE",
});

Configuration Options

Required Options

apiKey (string)

Your SiteAssist project publishable key. Get this from your dashboard under Advanced → API Keys → Publishable Keys.

SiteAssist("init", {
  apiKey: "pk_live_abc123...",
});

Widget Type Options

type (string)

Defines the widget type. Default: "floating-bubble"

Options:

  • "floating-bubble" - Floating chat button with expandable interface
  • "sidepanel" - Fixed side panel integration
// Floating bubble (default)
SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  type: "floating-bubble",
});

// Sidepanel
SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  type: "sidepanel",
});

Theme Options

theme (string)

Controls the widget's color scheme. Default: "auto"

Options:

  • "auto" - Automatically matches system preference
  • "light" - Always use light theme
  • "dark" - Always use dark theme
SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  theme: "dark", // Force dark theme
});

You can also change the theme dynamically:

// Change to light theme
SiteAssist("changeTheme", "light");

// Change to dark theme
SiteAssist("changeTheme", "dark");

// Change to auto (system preference)
SiteAssist("changeTheme", "auto");

Sidepanel Options

appContainerSelector (string)

CSS selector for the container that should be pushed when the sidepanel opens. Only applies when type: "sidepanel".

Default: ".siteassist-container"

SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  type: "sidepanel",
  appContainerSelector: ".main-content", // Custom selector
});

HTML Structure Example:

<div class="main-content">
  <!-- Your app content here -->
  <!-- This will be pushed right when sidepanel opens -->
</div>

Responsive Behavior:

  • On screens ≥1024px: Content is pushed by 400px
  • On screens <1024px: Sidepanel floats over content (no push)
  • On screens <768px: Full-screen mode automatically

Content Selection Options

contentSelector (boolean | string)

Controls where the text selection popover appears when users select text on your page.

Options:

  • true or undefined (default) - Only show popover when text is selected within .main-content elements
  • false - Show popover everywhere on the page (disable content filtering)
  • string - Custom CSS selector for where the popover should appear
// Default behavior - only in .main-content elements
SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  contentSelector: true, // or omit entirely
});

// Disable content filtering - show popover everywhere
SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  contentSelector: false,
});

// Custom selector - only in .main-content elements
SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  contentSelector: ".main-content",
});

// Only in article content
SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  contentSelector: "article .content",
});

HTML Structure Example:

<!-- With default contentSelector (true) -->
<div class="sidebar">
  <p>This text won't show the selection popover</p>
</div>

<div class="main-content">
  <p>This text WILL show the selection popover</p>
</div>

<!-- With custom contentSelector -->
<div class="article-content">
  <p>This text will show the selection popover</p>
</div>

Use Cases:

  • Documentation sites: Restrict to main content areas
  • Blogs: Only allow selection in article content
  • E-commerce: Enable everywhere for product help
  • Admin panels: Restrict to specific content sections

Advanced Options

externalId (string)

Optional identifier for the user. Useful for tracking specific users or personalizing experiences.

SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  externalId: "user_12345", // Your internal user ID
});

Note: Full user identification features (email, name, attributes) are coming soon.

widgetUrl (string)

Custom widget hosting URL. Only needed for self-hosted or custom deployments.

Default: "https://widgets.siteassist.io"

SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  widgetUrl: "https://custom-widgets.yourdomain.com",
});

apiUrl (string)

Custom API endpoint URL. Only needed for custom deployments.

Default: "https://api.siteassist.io"

SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  apiUrl: "https://custom-api.yourdomain.com",
});

Dashboard Customization

Many visual customization options are configured through the SiteAssist dashboard under Project Settings → Widget Appearance:

Colors & Branding

Configure these in your dashboard:

  • Brand Color - Primary accent color for the widget
  • Brand Color (Dark Mode) - Primary color for dark theme
  • User Message Bubble Color - Color for user messages
  • User Message Bubble Color (Dark Mode) - User message color in dark mode
  • Chat Button Color - Background color for the floating button

Positioning & Layout

  • Position - Choose bottom-left or bottom-right
  • Width - Widget width in pixels (default: 400px)
  • Max Height - Maximum height in pixels (default: 700px)
  • Offset - X and Y offset from corner in pixels
  • Base Font Size - Base font size in pixels (default: 16px)

Content & Messaging

  • Welcome Message - First message users see
  • Input Placeholder - Placeholder text in the input field
  • Header Title - Title shown in the widget header
  • Assistant Avatar - Custom avatar image URL
  • Chat Button Icon - Custom icon for the chat button

Behavior

  • Open Delay - Auto-open delay in milliseconds (0 = disabled)

Complete Configuration Example

Here's a full example combining multiple options:

SiteAssist("init", {
  // Required
  apiKey: "pk_live_abc123def456",

  // Widget type
  type: "floating-bubble",

  // Theming
  theme: "auto",

  // Content selection
  contentSelector: ".main-content", // Only show popover in main content

  // User tracking
  externalId: "user_12345",

  // Advanced (usually not needed)
  widgetUrl: "https://widgets.siteassist.io",
  apiUrl: "https://api.siteassist.io",
});

Configuration Best Practices

1. Use Environment Variables

Store your publishable key securely using environment variables:

// Next.js example
SiteAssist("init", {
  apiKey: process.env.NEXT_PUBLIC_SITEASSIST_PUBLISHABLE_KEY,
  theme: "auto",
});

2. Conditional Configuration

Configure differently based on environment:

SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  theme: "auto",
  // Use development widget URL in dev environment
  ...(process.env.NODE_ENV === "development" && {
    widgetUrl: "http://localhost:3000",
  }),
});

3. User-Based Theme

Set theme based on user preference:

const userPreference = localStorage.getItem("theme") || "auto";

SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  theme: userPreference,
});

4. Dynamic External ID

Set external ID based on logged-in user:

const userId = getCurrentUser()?.id;

SiteAssist("init", {
  apiKey: "YOUR_API_KEY",
  externalId: userId || null,
});

Testing Your Configuration

After configuring the widget, verify it's working correctly:

1. Visual Inspection

  • Widget appears in the correct position
  • Colors match your configuration
  • Theme is applied correctly

2. Console Verification

Open browser DevTools and check:

// Check if SiteAssist is loaded
console.log(window.SiteAssist);

// Should show a function if loaded correctly

3. Interaction Testing

  • Click to open/close the widget
  • Test theme changes
  • Verify sidepanel behavior (if applicable)
  • Test text selection feature

4. Responsive Testing

Test on different screen sizes:

  • Desktop (>1024px)
  • Tablet (768px - 1024px)
  • Mobile (<768px)

Troubleshooting

Widget position is wrong

Check your dashboard settings for position and offset values.

Colors not applying

Dashboard settings override any code-level color configurations. Update colors in your SiteAssist dashboard.

Sidepanel not pushing content

Ensure your container has the correct class or matches the appContainerSelector:

<div class="siteassist-container">
  <!-- or -->
</div>
<div class="your-custom-selector">
  <!-- if using appContainerSelector: ".your-custom-selector" -->
</div>

Theme not changing

Make sure you're calling changeTheme after initialization:

// Initialize first
SiteAssist("init", { apiKey: "YOUR_API_KEY" });

// Then change theme
SiteAssist("changeTheme", "dark");

Next Steps

Need help with configuration? Contact us at support@siteassist.io