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
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
https://app.hellocobi.com/embed/chat?key=cobi_embed_...&theme=dark

​
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

​
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

  • Key hashing: Keys are hashed at rest. Only the first 18 characters are stored for display.
  • Origin enforcement: When configured, only requests from allowed origins are accepted.
  • Data source isolation: The data source is locked to the key. It cannot be changed by the client.
  • Scoped access: Embed requests have restricted access and cannot view internal documents.
  • No cookies: The widget does not use cookies or require user authentication.

​
Managing Keys

From Developer > Channels you can:
  • View keys: See all active embed keys with their allowed origins and status
  • Delete keys: Permanently revoke a key. Any site using it will immediately lose access.
Deleting a key takes effect on the next request — there is 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 persistent, check browser console

​
Support

Need help with the embed widget? Contact us at [email protected].