Skip to main content

​
Overview

The Cobi chat widget can be embedded on any website as an iframe. Visitors interact with your AI assistant directly on your site. Authentication is handled via embed API keys that you create in the Cobi dashboard.
Embed keys are scoped to a single data source and can be restricted to specific domains for production use.

​
Getting Started

1

Create an Embed Key

Navigate to Developer > Channels in the Cobi dashboard. Click Create Embed Key and fill in:
FieldDescription
NameA label for this key (e.g. “Production website”)
Data SourceThe data source the embed will query against
Allowed Origins (optional)Domains permitted to load the widget (e.g. https://yoursite.com)
Expiry Date (optional)When the key should expire. Leave blank for no expiry
Chat History (optional)Allow this key to access conversation history. Must be enabled here before the chatHistory URL parameter has any effect
The full API key is only shown once at creation time. Copy the embed snippet immediately. You won’t be able to retrieve the full key later.
2

Add the Iframe to Your Site

After creating the key, you’ll see an embed snippet. Copy and paste it into your website’s HTML:
<iframe
  src="https://app.hellocobi.com/embed/chat?key=cobi_embed_your_key_here"
  style="width: 100%; height: 600px; border: none; border-radius: 8px;"
  allow="clipboard-write"
  title="Cobi Chat"
></iframe>
3

Verify It Works

Load your page in a browser. The chat widget should appear and respond to messages using your configured data source.

​
Configuration

​
URL Parameters

The embed URL supports the following query parameters:
ParameterRequiredDescription
keyYesYour embed API key
themeNolight, dark, or system (default). Matches the widget’s appearance to your site
chatHistoryNotrue to show the chat history panel. Only takes effect if history was enabled when the embed key was created
userIdNoAn identifier for the current user. See User Identity below
https://app.hellocobi.com/embed/chat?key=cobi_embed_...&theme=dark&chatHistory=true&userId=user_123

​
Allowed Origins

When you specify allowed origins during key creation, only those domains can load the widget. Requests from other origins are rejected with a 403 error.
  • Leave empty during development to allow any origin
  • For production, always specify your exact domains (e.g. https://yoursite.com)
  • The Origin header is required when allowed origins are configured
You can add multiple allowed origins to a single key, for example if your site is accessible on both https://example.com and https://www.example.com.

​
Theming

The widget respects light and dark mode via the theme parameter:
ValueBehavior
systemMatches the user’s OS preference (default)
lightForces light mode
darkForces dark mode

​
Chat History

Chat history lets users return to previous conversations in the widget. It is controlled by two things:
  1. Key setting: History must be enabled when creating the embed key in the dashboard. If it wasn’t, passing chatHistory=true in the URL has no effect.
  2. URL parameter: Even if the key supports history, you must pass chatHistory=true to make the history panel visible in the iframe.
This two-layer control lets you enable history on a key but selectively show it only on certain pages.

​
User Identity

By default, the widget generates a unique user ID per browser and stores it in localStorage. A returning visitor on the same browser is recognised as the same user and can see their previous chats, but the same user on a different device starts fresh. To share chat history across browsers, pass your own userId: 
<iframe
  src="https://app.hellocobi.com/embed/chat?key=cobi_embed_...&userId=user_abc123"
  style="width: 100%; height: 600px; border: none; border-radius: 8px;"
  allow="clipboard-write"
  title="Cobi Chat"
></iframe>
Pass a stable, per-user identifier from your own auth system (e.g. a database user ID). Do not use personally identifiable information such as email addresses as the userId.

​
Available Connections

The embed widget queries whichever data source you select when creating the embed key. All data source types supported by Cobi are available:
TypeNotes
PostgreSQLPostgreSQL 12+
MySQLMySQL 8.0+
MongoDBMongoDB Atlas and self-hosted instances. See MongoDB for schema conventions
The data source is locked to the key at creation time and cannot be changed by the client.

​
Rate Limiting

Each embed key is rate-limited to 1,000 requests per hour. When the limit is exceeded:
  • The API returns 429 Too Many Requests with a Retry-After header
  • The widget displays a user-friendly message asking the visitor to wait
If you need higher limits, contact the Cobi team at [email protected].

​
Security

Keys are hashed at rest and only the first 18 characters are stored for display. When allowed origins are configured, requests from any other domain are rejected outright. The data source is locked to the key at creation time and cannot be changed by the client. Embed requests have restricted access and cannot view internal documents. The widget does not use cookies or require user authentication.

​
Managing Keys

From Developer > Channels you can view all active embed keys along with their allowed origins and status, and permanently revoke any key. When a key is deleted it takes effect on the next request with no delay or grace period.

​
Troubleshooting

IssueCauseSolution
Widget shows “Missing API Key”No key parameter in the URLCheck the iframe src includes ?key=cobi_embed_...
403 errorOrigin not in allowed listAdd your domain to the key’s allowed origins, or leave origins empty for testing
401 errorKey is invalid, expired, or deletedCreate a new embed key in Developer > Channels
429 errorRate limit exceededWait for the rate limit window to reset (1 hour)
Widget crashes / white screenJavaScript errorThe widget includes an error boundary. Try refreshing. If it persists, check the browser console