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)
`api_filters`	array	-	Filters always applied to every request, not shown in UI (see API 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
`NEW_CHAT_BUTTON`	"New chat"	Text for the new chat button (chat mode only)

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

Filters add a dropdown UI above the chat input, letting users refine their search. Each filter object has these fields:

Field	Type	Description
`property`	string	The metadata field name to filter on
`title`	string	Display label shown in the dropdown
`type`	string	Comparison type: `"eq"` (exact match) or `"contains"`
`widget`	string	UI type: `"single"` (select one) or `"multiple"` (select many)
`choices`	array	Array of `{ value, label }` objects

<script>
var SERENITY_WIDGET = {
    api_url: "https://your-instance.serenitygpt.com/api/v2/",
    api_token: "your-api-token-here",
    filters: [
        {
            property: "category",
            title: "Category",
            type: "eq",
            widget: "single",
            choices: [
                { value: "docs", label: "Documentation" },
                { value: "api", label: "API Reference" },
                { value: "tutorials", label: "Tutorials" }
            ]
        },
        {
            property: "product",
            title: "Product",
            type: "eq",
            widget: "multiple",
            choices: [
                { 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>

With API Filters

Unlike UI filters (which render dropdowns for users to interact with), api_filters are hidden filters always sent with every request. This is useful when you want to restrict the widget to a specific subset of your data without exposing that choice to the user.

Each API filter object has these fields:

Field	Type	Description
`type`	string	Comparison type: `"eq"` (exact match) or `"contains"`
`property`	string	The metadata field name to filter on
`value`	string or string[]	The value(s) to match

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

You can combine api_filters with UI filters — both will be merged and sent together with each request.

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) {
        window.mountSerenityWidget(); // call this to mount the widget
    }
});
</script>

JavaScript API

The widget exposes global functions you can call from your own JavaScript code:

`window.mountSerenityWidget()`

Manually mount the widget. Useful when automount is set to false.

`window.serenityPrompt(text)`

Programmatically send a question to the widget. The text is submitted immediately as if the user typed and pressed Enter.

// Example: trigger a question from a custom button
document.getElementById('my-button').addEventListener('click', () => {
    window.serenityPrompt('How do I reset my password?');
});

`window.updateSerenityWidgetSettings(newSettings)`

Update widget configuration at runtime. The widget will unmount, apply the new settings, and remount automatically. Accepts a partial settings object — only the provided fields are updated.

// Example: switch to question mode and change the placeholder
window.updateSerenityWidgetSettings({
    mode: "question",
    labels: {
        CHAT_PLACEHOLDER: "Ask a quick question..."
    }
});

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