Getting Started with SiteSage Chat

The sitesage-chat module is a lightweight Web Component that provides a ready-to-use chat interface for your application. It supports localization, SPA routing, and custom styling.

Quick Start

To add the SiteSage Chat to your site, include the script via CDN and add the custom element to your HTML.

1. Include the Script

Add the following script tag to the <head> tag of your page:

<script src="https://cdn.jsdelivr.net/npm/@sitesage/webcomponents@0.0.5/dist/webcomponents.iife.js"></script>

The latest version can be found on jsDelivr.

2. Add the Component

Place the <sitesage-chat> tag in your HTML body. You will need your client_id, app_url, and backend_url from your SiteSage Admin.

<sitesage-chat
    client_id="YOUR_CLIENT_ID"
    app_url="YOUR_APP_URL"
    backend_url="YOUR_BACKEND_URL"
/>

Configuration Properties

The component accepts the following attributes:

Attribute	Type	Description
`client_id`	string	(Required) Your SiteSage Client ID
`app_url`	string	(Required) Your SiteSage App URL
`backend_url`	string	(Required) Your SiteSage Backend URL
`icon`	string	URL to a square image for the chat launcher icon.
`header_icon`	string	URL to a square image. Will add a header to the chat window with the image.
`use_router`	boolean	If present, enables SPA-friendly navigation (popstate/pushState).
`open`	boolean	Controls the visibility state of the chat window.
`disable_navigation`	boolean	If present, disables the chat window navigation buttons.

Features & Customization

Localization

To change the language, obtain a reference to the element and update the user property with a language code (e.g., da-DK for Danish).

const chat = document.querySelector('sitesage-chat');
chat.user = {
    language: 'da-DK'
};

Custom Styling

You can customize the chat window and widget by adding CSS properties to the sitesage-chat element.

sitesage-chat {
    --ss-chat-avatar: url('https://api.sitesage.ai/res/logo.png');
    --ss-chat-header-bg: linear-gradient(to right, red, blue);
}

For a full list of CSS variables, refer to the CSS Variables reference page.

Single Page Applications (SPA)

If you are using a framework like React or Vue, adding the use_router attribute ensures that links clicked inside the chat use the browser’s history API instead of causing a full page reload.

Custom Icon

For the best appearance, use a square image. Large images should be avoided and will be scaled to fit the launcher button.

Events

The component emits events that you can listen to for custom logic (like analytics tracking or UI changes).

Event	Description
`open`	Fired when the chat window is opened.
`close`	Fired when the chat window is closed.
`link:open`	Fired when a link is clicked inside the chat.
`proxy:request`	Fired when the chat needs to make an (authenticated) request to the backend.

Please refer to the widget documentation for more information on how to override the default proxy handler. Overriding the proxy handler allows you to send admin-level requests to the AI.

Example: Listetning for Open Events

const chat = document.querySelector('sitesage-chat');

chat.addEventListener('app:open', () => {
    console.log("User opened the chat!");
});

Example: Minimal Implementation

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Minimal Implementation Example</title>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@sitesage/webcomponents@0.0.5/dist/webcomponents.iife.js"></script>
</head>
<body>
    <sitesage-chat
        disable_navigation
        client_id="ss-pub-guest"
        header_icon="https://placehold.co/256x128"
        icon="https://placehold.co/128x128"
        app_url="<your app url>"
        backend_url="<your backend url>"
    />
</body>
</html>

<style>
    sitesage-chat {
        --ss-chat-avatar: url('https://placehold.co/128x128');
        --ss-chat-header-bg: linear-gradient(to right, #07346b, #1c4980);
    }
</style>