The GiiS Website Widget allows you to embed AI-powered chat directly on any website.

Features include:

• Lightweight ~100-150kb gzipped bundle
• Fully customizable colors and branding
• Responsive design (desktop popup, mobile fullscreen)
• Real-time streaming responses via SSE
• Session persistence across page reloads

Deployment Options

Cloud Deployment (Recommended)

For GiiS Cloud users, the widget is served from GiiS's CDN. Simply add the following to your website:

<!-- Load the widget -->
<script type="module" src="https://cdn.giis.ai/widget/1.1/dist/giis-widget.js"></script>

<!-- Configure and display -->
<giis-chat-widget
  backend-url="https://cloud.giis.ai/api"
  api-key="your_api_key_here"
  mode="launcher"
>
</giis-chat-widget>

Self-Hosted Deployment

For self-hosted GiiS instances, you'll need to build and host the widget yourself.

Clone the repository

Clone the GiiS repository from GitHub.

Navigate to widget directory

    cd widget/
    ```

### Install dependencies

```bash
    npm install
    ```

### Obtain a widget API key

Navigate to your GiiS admin panel and create a new API key specifically for the widget.


    ::: warning
      Create a **limited-scope API key** with only chat permissions.
      Never use admin or full-access keys since the API key will be visible in client-side code.

### Configure environment (optional)

For builds with baked-in configuration, create a `.env` file:

    ```bash
    cp .env.example .env
    ```

    Edit `.env` and set your backend URL and API key:

    ```
    VITE_WIDGET_BACKEND_URL=https://your-backend.com
    VITE_WIDGET_API_KEY=your_api_key
    ```

### Build the widget

For **cloud-style deployment** (config via HTML attributes):

    ```bash
    npm run build:cloud
    ```

    For **self-hosted deployment** (config baked into bundle):

    ```bash
    npm run build:self-hosted
    ```

### Deploy the bundle

Upload `dist/giis-widget.js` to your CDN or web server.

### Customer Embed Code

After deployment, provide customers with the embed code:

**Cloud-style (attributes required):**

```html
<script type="module" src="https://your-cdn.com/giis-widget.js"></script>
<giis-chat-widget
  backend-url="https://your-backend.com"
  api-key="customer_api_key"
  agent-name="Support"
  logo="https://path-to-your-logo.com/"
>
</giis-chat-widget>

Self-hosted (config baked in):

<script type="module" src="https://your-cdn.com/giis-widget.js"></script>
<giis-chat-widget
  agent-name="Support"
  logo="https://path-to-your-logo.com/"
>
</giis-chat-widget>

Configuration Reference

Required Attributes

Attribute	Type	Description
backend-url	string	Your GiiS backend API URL
api-key	string	API key for authentication

backend-url

The URL of your GiiS backend API. This is where the widget sends chat requests.

• GiiS Cloud: Use https://cloud.giis.ai or your tenant-specific URL
• Self-hosted: Use your GiiS instance URL (e.g., https://giis.yourcompany.com)

<!-- GiiS Cloud -->
<giis-chat-widget backend-url="https://cloud.giis.ai/api" ...></giis-chat-widget>

<!-- Self-hosted -->
<giis-chat-widget backend-url="https://giis.yourcompany.com" ...></giis-chat-widget>

api-key

A valid GiiS API key for authenticating widget requests. This key is visible in client-side code, so always use a limited-scope key.

<giis-chat-widget
  backend-url="https://cloud.giis.ai/api"
  api-key="on_abc123xyz789"
  ...
></giis-chat-widget>

INFO

For self-hosted builds with baked-in config, backend-url and api-key can be set via environment variables during build instead of HTML attributes.

Optional Attributes

Attribute	Type	Default	Description
agent-id	number	undefined	Specific agent/persona to use
agent-name	string	"Assistant"	Display name in header
logo	string	GiiS logo	URL to custom logo image
primary-color	string	#1c1c1c	Primary brand color (buttons, accents)
background-color	string	#e9e9e9	Widget background color
text-color	string	#000000bf	Text color (75% opacity black)
mode	string	"launcher"	Display mode: "launcher" or "inline"
include-citations	boolean	false	Show citation badges linking to source documents

include-citations

When enabled, assistant messages display clickable citation badges below the response text. Each badge shows a sequential number and the source document title, linking directly to the original document.

<giis-chat-widget
  backend-url="https://cloud.giis.ai/api"
  api-key="on_abc123"
  include-citations="true"
>
</giis-chat-widget>

WARNING

Be mindful of document access when enabling citations. The widget will cite any documents accessible to the configured agent or API key. If the agent has access to private or internal documents, citation links may point to resources that end users do not have permission to view.

To avoid exposing private document links, either scope the agent's document access to only public-facing sources, or disable citations for public-facing widget deployments.

API Key Security

The widget's API key is exposed in client-side code. Always create a dedicated API key with:

• Limited permissions - Only chat access, no admin features
• Rate limiting - Prevent abuse from malicious actors
• Monitoring - Track usage and detect anomalies

:::

Create a widget-specific API key

In your GiiS admin panel, create a new API key with minimal permissions.

Enable rate limiting

Configure rate limits appropriate for your expected usage.

Monitor usage

Regularly review API key usage for unusual patterns.

Browser Support

• Chrome/Edge 90+ (Chromium)
• Firefox 90+
• Safari 15+
• Mobile Safari (iOS 15+)
• Mobile Chrome (Android)

INFO

Need help with setup? Contact your GiiS administrator for API key configuration or deployment assistance.