@dialektai/widget

Framework-agnostic widget for embedding DialektAI natural language database queries into your application. Works with React, Vue, Angular, Svelte, and vanilla JavaScript.

Installation

npm install @dialektai/widget

For React apps, you also need to install peer dependencies:

npm install react react-dom axios socket.io-client

Or with yarn:

yarn add @dialektai/widget
yarn add react react-dom axios socket.io-client

⚠️ Important: Import the Correct Build

For React apps, you MUST use the /react import:

// ✅ CORRECT - Uses your app's React (no conflicts)
import { DialektAIWidget } from '@dialektai/widget/react';

// ❌ WRONG - Bundles its own React (causes hook errors)
import { DialektAIWidget } from '@dialektai/widget';

See TROUBLESHOOTING.md if you encounter "Invalid hook call" errors.

Quick Start

React

import { DialektAIWidget } from '@dialektai/widget/react';

function App() {
  return (
    <DialektAIWidget
      apiKey="pk_your_api_key_here"
      databaseId="your-database-id"
      scopeId={user.id}
      tenantId={user.organizationId}
      theme="light"
    />
  );
}

Vue 3

<template>
  <DialektAIWidget
    api-key="pk_your_api_key_here"
    database-id="your-database-id"
    :scope-id="user.id"
    :tenant-id="user.organizationId"
    theme="light"
  />
</template>

<script setup>
import { DialektAIWidget } from '@dialektai/widget/vue';
</script>

Vanilla JavaScript

<!-- Include the widget script -->
<script src="https://cdn.dialektai.com/widget/latest/widget.js"></script>

<!-- Add widget container -->
<div id="dialektai-widget"></div>

<script>
  // Initialize the widget
  DialektAI.embed({
    containerId: 'dialektai-widget',
    apiKey: 'pk_your_api_key_here',
    databaseId: 'your-database-id',
    scopeId: 'user-123',
    tenantId: 'org-456',
    theme: 'light',
  });
</script>

Props/Options

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | ✅ Yes | Your DialektAI public API key | | databaseId | string | ⚠️ Recommended | Specific database to query | | scopeId | string \| number | ⚠️ Recommended | User/scope ID for conversation history | | tenantId | string \| number | ⚠️ Recommended | Organization/tenant ID for data filtering (multi-tenancy) | | personalityId | string | ❌ No | AI personality to use for responses | | theme | 'light' \| 'dark' | ❌ No | Widget theme (default: 'light') | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | ❌ No | Widget position (default: 'bottom-right') | | height | number | ❌ No | Widget height in pixels (default: 600) | | placeholder | string | ❌ No | Input placeholder text | | enableLinks | boolean | ❌ No | Enable contextual links (default: true) | | qaEnabled | boolean | ❌ No | Enable Q&A suggestions (default: true) |

Usage with Authentication

Wait for user authentication before rendering the widget:

import { DialektAIWidget } from '@dialektai/widget/react';

function App() {
  const { user, isLoading } = useAuth();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!user) {
    return <div>Please log in</div>;
  }

  return (
    <DialektAIWidget
      apiKey={process.env.REACT_APP_DIALEKTAI_API_KEY}
      databaseId={process.env.REACT_APP_DATABASE_ID}
      scopeId={user.id}
      tenantId={user.organizationId}
      theme="light"
    />
  );
}

TypeScript Support

Full TypeScript support with type definitions included:

import { DialektAIWidget, ChatWidgetProps } from '@dialektai/widget/react';

const widgetProps: ChatWidgetProps = {
  apiKey: 'pk_...',
  databaseId: 'db-...',
  scopeId: 123,
  tenantId: 456,
  theme: 'dark',
};

<DialektAIWidget {...widgetProps} />

Configuration

API Key

Get your API key from the DialektAI dashboard:

1. Go to your database settings
2. Navigate to the "Widget" tab
3. Create or copy a public API key

User Context (Recommended for Production)

• scopeId: Unique identifier for the user/session. Used for saving conversation history per user.
• tenantId: Organization/tenant identifier. Used for multi-tenant data filtering and security.

For testing, you can omit these to create anonymous sessions. However, for production use, both are strongly recommended.

Database Selection

• databaseId: Specify which database to query. If not provided, the default database associated with your API key will be used.

Security

• API keys are public keys (safe to embed in client code)
• Security is enforced through:
  • CORS: Configure allowed origins in your database settings
  • Tenant Isolation: Data is filtered by tenantId when provided
  • Rate Limiting: API keys have rate limits to prevent abuse

Features

• ✅ Natural language database queries
• ✅ Multi-database support (PostgreSQL, MySQL, SQL Server, SQLite, Oracle, MongoDB, Snowflake, Databricks, Redshift, BigQuery)
• ✅ Conversation history per user
• ✅ Multi-tenancy support with tenant-based data filtering
• ✅ Customizable themes (light/dark)
• ✅ AI personalities for custom response styles
• ✅ Contextual links and Q&A suggestions
• ✅ TypeScript support
• ✅ Framework-agnostic (React, Vue, vanilla JS)
• ✅ Fully isolated error handling (never crashes host app)

Examples

Basic Widget

<DialektAIWidget
  apiKey="pk_..."
  databaseId="db-..."
  scopeId={user.id}
  tenantId={user.organizationId}
/>

Custom Styling

<DialektAIWidget
  apiKey="pk_..."
  databaseId="db-..."
  scopeId={user.id}
  tenantId={user.organizationId}
  theme="dark"
  position="bottom-left"
  height={700}
/>

With Custom Personality

<DialektAIWidget
  apiKey="pk_..."
  databaseId="db-..."
  personalityId="personality-123"
  scopeId={user.id}
  tenantId={user.organizationId}
/>

Anonymous Session (Testing)

<DialektAIWidget
  apiKey="pk_..."
  databaseId="db-..."
  theme="light"
/>

Vanilla JavaScript API

Methods

// Create a widget
const widgetId = DialektAI.create('#container', {
  apiKey: 'pk_...',
  databaseId: 'db-...',
  scopeId: 'user-123',
  tenantId: 'org-456',
});

// Embed with configuration
DialektAI.embed({
  containerId: 'dialektai-widget',
  apiKey: 'pk_...',
  databaseId: 'db-...',
  onReady: () => console.log('Widget ready'),
  onError: (error) => console.error('Widget error:', error),
});

// Destroy a widget
DialektAI.destroy(widgetId);

// Auto-initialize from HTML attributes
DialektAI.init();

HTML Attributes (Auto-initialization)

<div
  data-dialekt-ai-widget
  data-api-key="pk_..."
  data-database-id="db-..."
  data-scope-id="user-123"
  data-tenant-id="org-456"
  data-theme="light"
  data-position="bottom-right"
></div>

Troubleshooting

Widget not appearing

• Check that you've provided a valid API key
• Verify the API key is active in your dashboard
• Check browser console for errors
• Ensure the container element exists (for programmatic initialization)

No responses from queries

• Verify API key is active
• Check allowed origins in database settings (CORS)
• Ensure database is properly configured and connected
• Verify databaseId is correct (if specified)

Conversation history not persisting

• Ensure scopeId is provided and consistent for the same user
• Check that scopeId is unique per user (not shared)

Multi-tenancy not working

• Ensure tenantId is provided
• Verify your database connection has requires_organization_scoping enabled
• Check that data contains the tenant filtering column

Error Handling

The widget is fully isolated and will never crash your host application. All errors are caught and handled internally with graceful fallbacks.

<DialektAIWidget
  apiKey="pk_..."
  // Even with invalid props, your app won't crash
  databaseId="invalid-id"
/>

Support

For issues, questions, or feature requests:

• Email: [email protected]
• Documentation: https://docs.dialektai.com
• Dashboard: https://app.dialektai.com

License

UNLICENSED - Proprietary software