Website Widget - Gorbit Documentation

The Gorbit 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 Gorbit Cloud users, the widget is served from Gorbit’s CDN. Simply add the following to your website:

<!-- Load the widget -->
<script type="module" src="https://cdn.gorbit.app/widget/1.0/dist/gorbit-widget.js"></script>

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

Self-Hosted Deployment

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

Clone the repository

Clone the Gorbit repository from GitHub.

Navigate to widget directory

cd widget/

Install dependencies

npm install

Obtain a widget API key

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

Creating a widget API key in the Gorbit admin panel

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:

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):

npm run build:cloud

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

npm run build:self-hosted

Deploy the bundle

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

Customer Embed Code

After deployment, provide customers with the embed code: Cloud-style (attributes required):

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

Self-hosted (config baked in):

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

Configuration Reference

Required Attributes

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

`backend-url`

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

Gorbit Cloud: Use https://cloud.gorbit.app or your tenant-specific URL
Self-hosted: Use your Gorbit instance URL (e.g., https://gorbit.yourcompany.com)

<!-- Gorbit Cloud -->
<gorbit-chat-widget backend-url="https://cloud.gorbit.app/api" ...></gorbit-chat-widget>

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

`api-key`

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

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

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	Gorbit 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"`

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 Gorbit 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)

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

​Deployment Options

​Cloud Deployment (Recommended)

​Self-Hosted Deployment

​Customer Embed Code

​Configuration Reference

​Required Attributes

​backend-url

​api-key

​Optional Attributes

​API Key Security

​Browser Support

Deployment Options

Cloud Deployment (Recommended)

Self-Hosted Deployment

Customer Embed Code

Configuration Reference

Required Attributes

`backend-url`

`api-key`

Optional Attributes

API Key Security

Browser Support