Chat Widget - Quick Start Guide

Get the dialektai chat widget embedded on your website in under 5 minutes.

What You'll Need

Step 1: Get Your API Key

  1. Log in to the dialektai portal
  2. Navigate to your database details page
  3. Scroll to the Widget Integration section
  4. Click Generate API Key
  5. Give it a name (e.g., "Website Widget")
  6. Copy the API key (it's shown only once!)

Step 2: Configure CORS

Add your website domain to allowed origins:

  1. In the same Widget Integration section
  2. Find Allowed Origins
  3. Add your domain: https://yourwebsite.com
  4. Click Save

Important: Use your actual domain, not localhost (unless testing)

Step 3: Add Widget to Your Website

Add this code to your HTML where you want the chat widget:

<!-- Container for the widget -->
<div data-dialekt-ai-widget
     data-api-key="YOUR_API_KEY_HERE"
     data-database-id="YOUR_DATABASE_ID"
     data-theme="light"
     data-position="bottom-right">
</div>

<!-- Widget script -->
<script src="https://widget.dialektai.com/widget.js"></script>

Replace:

Step 4: Test It!

  1. Open your website in a browser
  2. Look for the chat bubble in the bottom-right corner
  3. Click to open the widget
  4. Ask a question about your database!

Example questions:

Customization Options

Change Theme

data-theme="dark"    <!-- Dark mode -->
data-theme="light"   <!-- Light mode (default) -->
data-theme="auto"    <!-- Follows system preference -->

Change Position

data-position="bottom-right"  <!-- Default -->
data-position="bottom-left"
data-position="top-right"
data-position="top-left"

Custom Placeholder

data-placeholder="Ask me about your sales data..."

Use Specific AI Personality

data-personality-id="a1201dbc-0d37-4c74-8ea0-235f7466162b"

How to get your Personality ID:

  1. Log in to the dialektai portal
  2. Go to Settings → AI Personalities
  3. Find the personality you want to use
  4. Click the Copy button next to the Personality ID

Set Widget Height

data-height="500"  <!-- Height in pixels -->

Automatic Branding (Business+ Plans)

The widget automatically applies your organization's branding - no additional configuration needed!

Included with automatic branding:

How to set up:

  1. Log in to the dialektai portal
  2. Navigate to Settings → Branding
  3. Upload your logo and customize colors
  4. Save changes
  5. Your widget updates automatically!

Plan Requirements:

Example widget with automatic branding:

<!-- Widget automatically applies your branding -->
<div data-dialekt-ai-widget
     data-api-key="pk_key_abc123..."
     data-database-id="550e8400-e29b-41d4-a716-446655440000">
</div>
<script src="https://widget.dialektai.com/widget.js"></script>

That's it! Your custom logo, colors, and settings are applied automatically.

See Branding Configuration Guide for detailed setup instructions.

Complete Example

<!DOCTYPE html>
<html>
<head>
    <title>My Website with dialektai</title>
</head>
<body>
    <h1>Welcome to My Site</h1>

    <!-- dialektai Chat Widget -->
    <div data-dialekt-ai-widget
         data-api-key="pk_key_abc123..."
         data-database-id="550e8400-e29b-41d4-a716-446655440000"
         data-theme="auto"
         data-position="bottom-right"
         data-placeholder="Ask about our data...">
    </div>

    <script src="https://widget.dialektai.com/widget.js"></script>
</body>
</html>

Troubleshooting

Widget Not Showing

  1. Check console for errors: Open browser DevTools (F12) → Console tab
  2. Verify API key: Ensure it's correct and not revoked
  3. Check CORS: Make sure your domain is in allowed origins
  4. Script loaded: Verify widget.js loaded successfully in Network tab

"Unauthorized" Error

  1. API key is incorrect or revoked
  2. Domain not in CORS allowed origins
  3. Database API key used with wrong database ID

Widget Shows But Won't Query

  1. Database not connected or schema indexing failed
  2. Database requires tenant filtering but no data-tenant-id provided
  3. Check API key permissions

Advanced Integration

For programmatic control, use the JavaScript API:

// Create widget in specific container
const widgetId = DialektAI.create('#my-chat-container', {
  apiKey: 'your-api-key',
  databaseId: 'your-db-id',
  theme: 'auto'
});

console.log('Widget created with ID:', widgetId);

// Destroy widget when needed
DialektAI.destroy(widgetId);

// Using embed() for callbacks (advanced)
const embedWidgetId = DialektAI.embed({
  containerId: 'my-chat-container',
  apiKey: 'your-api-key',
  databaseId: 'your-db-id',
  theme: 'auto',
  onReady: () => console.log('Widget ready!'),
  onError: (error) => console.error('Error:', error)
});

Multi-tenant Support

If you have a multi-tenant application (SaaS), filter data by customer:

<div data-dialekt-ai-widget
     data-api-key="YOUR_API_KEY"
     data-database-id="YOUR_DB_ID"
     data-tenant-id="customer-123"
     data-scope-id="550e8400-e29b-41d4-a716-446655440000">
</div>

Note: Your database must have requires_organization_scoping = true enabled in the configuration.

Next Steps

Last updated: 2025-11-06