Embedding SerenityGPT Widget component

This guide explains how to embed SerenityGPT chat component into your applications and custom web pages.

Basic Integration

To add the SerenityGPT chat widget to your webpage:

Add the following script tags to your HTML file:

<script>
var SERENITY_WIDGET = {
    api_url: "https://<your-backend-url>",
    api_token: "<your-token-here>"
};
</script>
<script type="module" src="https://js.serenitygpt.com/widget.js"></script>

You can obtain url and token from admin portal (or ask Serenity Team to help you obtain it for your special case)

Insert a container element where you want the chat widget to appear:

<div id="serenity"></div>

Overview

The SerenityGPT widget is a flexible chat component that can operate in two modes: - Chat Mode: Full conversational interface with message history - Question Mode: Simple question-answer interface

The widget can be displayed as either: - Popup: Floating button that opens a modal dialog - Inline: Embedded directly into your page content

Configuration Options

All configuration options are set through the SERENITY_WIDGET global object. Here's a complete reference:

Core Settings

Option	Type	Default	Description
`api_url`	string	-	Required. Your SerenityGPT backend API URL
`api_token`	string	-	Required. Your API authentication token
`el`	string	`"serenity"`	ID of the HTML element where the widget will mount
`mode`	string	`"chat"`	Widget mode: `"chat"` or `"question"`
`popup`	boolean	`true`	Display as popup (`true`) or inline (`false`)
`automount`	boolean	`true`	Automatically mount the widget when the script loads
`debug`	boolean	`false`	Enable debug logging in console
`logo_url`	string	-	Custom logo URL to display in the widget

Content Settings

Option	Type	Default	Description
`examples`	string[]	-	Array of example questions to display
`filters`	array	-	Filter options for search refinement (see Filters section)
`default_filters`	object	-	Default filter values to apply on load

Label Customization

The labels object allows you to customize all text displayed in the widget:

Label Key	Default Text	Usage
`CHAT_PLACEHOLDER`	"Ask anything and get AI-generated answers..."	Input placeholder text
`POPUP_TITLE`	"Serenity Chat"	Title in popup mode
`POPUP_TRIGGER_TITLE`	"Ask anything and get answers"	Hover text for popup trigger button
`COLLAPSE_SHOW`	"Show more"	Expand collapsed content
`COLLAPSE_HIDE`	"Collapse"	Collapse expanded content
`DOCUMENTS_IN`	"Documents in response"	Header for referenced documents
`DOCUMENTS_OTHER`	"Other documents"	Header for additional documents
`DOWN_RATE_DETAILS_PLACEHOLDER`	"A high-level summary of what the correct answer should and/or should not mention."	Feedback form placeholder
`DOWN_RATE_URL_PLACEHOLDER`	"http://someurl.com/page"	URL input placeholder in feedback
`DOWN_RATE_BUTTON`	"Send"	Submit button text

Configuration Examples

<script>
var SERENITY_WIDGET = {
    api_url: "https://your-instance.serenitygpt.com/api/v2/",
    api_token: "your-api-token-here"
};
</script>
<script type="module" src="https://js.serenitygpt.com/widget.js"></script>
<div id="serenity"></div>

Inline Question Mode

<script>
var SERENITY_WIDGET = {
    api_url: "https://your-instance.serenitygpt.com/api/v2/",
    api_token: "your-api-token-here",
    mode: "question",
    popup: false,
    el: "chat-widget"
};
</script>
<script type="module" src="https://js.serenitygpt.com/widget.js"></script>
...
<div id="chat-widget"></div>

Customized Labels and Examples

<script>
var SERENITY_WIDGET = {
    api_url: "https://your-instance.serenitygpt.com/api/v2/",
    api_token: "your-api-token-here",
    logo_url: "https://your-domain.com/logo.png",
    examples: [
        "How do I reset my password?",
        "What are your business hours?",
        "How can I contact support?"
    ],
    labels: {
        CHAT_PLACEHOLDER: "How can we help you today?",
        POPUP_TITLE: "Customer Support",
        POPUP_TRIGGER_TITLE: "Click here for help"
    }
};
</script>
<script type="module" src="https://js.serenitygpt.com/widget.js"></script>
...
<div id="serenity"></div>

With Filters

<script>
var SERENITY_WIDGET = {
    api_url: "https://your-instance.serenitygpt.com/api/v2/",
    api_token: "your-api-token-here",
    filters: [
        {
            property: "category",
            label: "Category",
            type: "select",
            options: [
                { value: "docs", label: "Documentation" },
                { value: "api", label: "API Reference" },
                { value: "tutorials", label: "Tutorials" }
            ]
        },
        {
            property: "product",
            label: "Product",
            type: "multiselect",
            options: [
                { value: "widget", label: "Widget" },
                { value: "api", label: "API" },
                { value: "dashboard", label: "Dashboard" }
            ]
        }
    ],
    default_filters: {
        category: "docs"
    }
};
</script>
<script type="module" src="https://js.serenitygpt.com/widget.js"></script>
<div id="serenity"></div>

Manual Mounting

If you need more control over when the widget initializes, you can disable auto-mounting:

<script>
var SERENITY_WIDGET = {
    api_url: "https://your-instance.serenitygpt.com/api/v2/",
    api_token: "your-api-token-here",
    automount: false
};
</script>
<script type="module" src="https://js.serenitygpt.com/widget.js"></script>

<script>
// Mount the widget later when needed
document.addEventListener('DOMContentLoaded', function() {
    // Widget will mount when this condition is met
    if (userIsLoggedIn) {
        // The widget will automatically mount when automount is re-enabled
        window.SERENITY_WIDGET.automount = true;
    }
});
</script>

Browser Support

The widget supports all modern browsers covering 99.5% of users, including:

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Mobile browsers

Troubleshooting

Ensure the container element exists in the DOM
Check browser console for any errors
Verify api_url and api_token are correctly set

API connection issues

Verify your API URL includes the /api/v2/ path
Ensure your API token is valid and has proper permissions
Check CORS settings on your API backend

Styling conflicts

The widget uses scoped styles to minimize conflicts
If needed, you can override styles using more specific CSS selectors

API Endpoints

The widget communicates with these backend endpoints:

POST /api/conversation/ - Chat conversations (list of queston for given conversation)
POST /api/questions/ - Question answering/streaming responses
GET /api/settings/ - Widget configuration - backen can adapt widget settings (usefull in case of wide installation to manage settings across all pages)

Styling Customization

The widget uses CSS custom properties (variables) that you can override to match your brand colors and theme.

Core CSS Variables

Add these CSS variables to your stylesheet to customize the widget appearance:

.serenity_app {
    /* Main colors */
    --serenity-widget-bg: #ffffff;                    /* Background color */
    --serenity-widget-text: #1a1a1a;                  /* Text color */
    --serenity-widget-primary: #e7ebe9;               /* Primary color (buttons, inputs) */
    --serenity-widget-secondary: #5a5a5a;             /* Secondary color (icons, borders) */
    --serenity-widget-accent: #007bff;                /* Accent color (links, highlights) */
    --serenity-widget-border: #e0e0e0;                /* Border color */
    --serenity-widget-hover: #f5f5f5;                 /* Hover state background */

    /* Shadows and effects */
    --serenity-widget-shadow-color: #0000001a;        /* Shadow color */
    --serenity-widget-shadow: var(--serenity-widget-shadow-color) 0px 2px 8px 0px;

    /* Example questions styling */
    --serenity-example-bg: #f8f9fa;                   /* Example question background */
    --serenity-example-text: #495057;                 /* Example question text */
    --serenity-example-border: #dee2e6;               /* Example question border */
    --serenity-example-shadow: 0px 1px 2px 0px rgba(0, 0, 0, 0.05);

    /* Other elements */
    --serenity-actions-opacity: 0.8;                  /* Action buttons opacity */
    --serenity-answer-code-bg: #f6f8fa;               /* Code block background */
}

Dark Theme Example

Here's a complete dark theme implementation:

<style>
.serenity_app.serenity_theme-dark {
    --serenity-widget-bg-opacity: 1;
    --serenity-widget-bg: rgb(42 36 33 / var(--serenity-widget-bg-opacity));
    --serenity-widget-text: #f0ebe8;
    --serenity-widget-primary: #60341a80;
    --serenity-widget-secondary: #8c5b3e;
    --serenity-widget-accent: #ffd2a7;
    --serenity-widget-border: #5a3b25;
    --serenity-widget-hover: #3a2a22;
    --serenity-widget-shadow-color: #00000065;
    --serenity-widget-shadow: var(--serenity-widget-shadow-color) 0px 6px 32px 0px;
    --serenity-example-bg: rgb(54 40 34);
    --serenity-example-text: rgb(243 206 179 / 1);
    --serenity-example-border: rgb(146 89 67 / 1);
    --serenity-example-shadow: 0px 1px 3px 0px rgba(0, 0, 0, .4), 0px .5px .5px .5px rgba(255, 255, 255, .1) inset;
    --serenity-actions-opacity: .9;
    --serenity-answer-code-bg: rgba(30, 25, 22, .7);
}
</style>

<script>
// Apply dark theme after widget loads
window.addEventListener('DOMContentLoaded', () => {
    document.querySelector('.serenity_app')?.classList.add('serenity_theme-dark');
});
</script>

Custom Brand Colors Example

/* Blue corporate theme */
.serenity_app {
    --serenity-widget-bg: #f8f9fa;
    --serenity-widget-text: #212529;
    --serenity-widget-primary: #e3f2fd;
    --serenity-widget-secondary: #1976d2;
    --serenity-widget-accent: #2196f3;
    --serenity-widget-border: #bbdefb;
    --serenity-widget-hover: #e1f5fe;
}

/* Green nature theme */
.serenity_app {
    --serenity-widget-bg: #f1f8e9;
    --serenity-widget-text: #1b5e20;
    --serenity-widget-primary: #c8e6c9;
    --serenity-widget-secondary: #388e3c;
    --serenity-widget-accent: #4caf50;
    --serenity-widget-border: #a5d6a7;
    --serenity-widget-hover: #dcedc8;
}

Styling Considerations

The widget automatically injects its CSS styles into your page
In popup mode, the widget creates a floating button in the bottom-right corner
In inline mode, the widget fills the width of its container element
The widget is responsive and works on mobile devices
Use the .serenity_app selector to target the widget container
CSS variables provide consistent theming across all widget components