Skip to main content

Using Waii via Widgets

Waii widgets provide a collection of pre-built UI components for integrating Waii's text-to-SQL capabilities into your application. The primary component is the WaiiChat widget, which offers a complete chat interface for interacting with your databases through natural language.

Why Use the Widget​

The WaiiChat widget offers several advantages over building a custom integration:

  • Reduces implementation time from weeks to hours
  • Handles all chat UI complexities including message threading, loading states, and error handling
  • Provides built-in SQL visualization and result formatting
  • Maintains consistent updates with Waii's API capabilities
  • Offers extensive customization options while maintaining reliability

Implementation Path​

The typical implementation process follows these steps:

  1. Database Setup

    • Use the Waii UI and CLI to load your database
    • Configure the database for text-to-SQL functionality
    • Verify the connection and data access

  2. User Configuration

    • Create and configure users who will access the widget
    • Set appropriate access levels for schemas, tables, columns, and rows
    • Generate necessary API credentials

  3. Widget Integration

    • Choose an integration method based on your needs
    • Configure the widget with your API key and database key
    • Customize the appearance and behavior as needed

Integration Options​

We provide three integration methods to accommodate different technical requirements and use cases. What follows is a quick rundown of each one and what they look like.

The snippets below are not meant to be full examples, if you want to get started right away: Example repository.

React Component and Standalone Script​

These methods are ideal for deep integrations where you want full control over the widget's behavior and appearance. They offer:

  • Complete control over the widget's lifecycle
  • Direct access to all widget events and states
  • Seamless integration with your application's styling
  • Ability to extend and customize functionality

React Component:

npm install @waii-ai/widgets

import { WaiiChat } from '@waii-ai/widgets';

function App() {
  return (
    <WaiiChat 
      apiKey="your-api-key"
      databaseKey="your-database-key"
    />
  );
}

Standalone Script:

<script src="https://unpkg.com/@waii-ai/widgets/dist/waii-widgets.js"></script>

<div id="waii-chat"></div>
<script>
  WaiiWidgets.WaiiChatLoader.init({
    containerId: 'waii-chat',
    apiKey: 'your-api-key',
    databaseKey: 'your-database-key'
  });
</script>

iFrame Embed​

The iFrame integration provides a lighter-weight approach, ideal for:

  • Quick overlays on existing applications
  • Situations where you want to minimize integration complexity
  • Cases where you need to isolate the widget from your main application
  • Testing or proof-of-concept implementations

Implementation:

<script src="https://unpkg.com/@waii-ai/widgets/dist/embed.js"></script>

<div id="chat-container"></div>
<script>
  const chatWidget = new WaiiWidgets.WaiiChatEmbed('#chat-container', {
    apiKey: 'your-api-key',
    databaseKey: 'your-database-key'
  });
</script>

Configuration​

All integration methods support a comprehensive set of configuration options:

Configuration Options​

Required Configuration​

  • apiKey: Your Waii API key for authentication
  • databaseKey: Your database connection string

Connection Options​

  • apiUrl: Custom API endpoint (if different from default)
  • model: Specify which AI model to use for query generation

UI Customization​

  • theme: 'light' or 'dark' mode
  • className: CSS class for the container element
  • style: Inline styles for the main container
  • contentStyle: Styles for the chat content area
  • messageListStyle: Styles for the message list container
  • inputStyle: Styles for the input area

Branding​

  • botName: Custom name for the chat bot
  • botAvatarUrl: Custom avatar URL for the bot

AI Behavior Configuration​

  • useFewShotLearning: Enable few-shot learning for improved accuracy
  • useReflection: Enable the model's reflection capabilities
  • useStrictHallucinationCheck: Enable strict checking to prevent hallucinated responses

State Management​

  • chatHistoryList: Pre-populate the chat with existing messages
  • selectedDBConnector: Set a specific database connector
  • chatQueryEdited: Pre-set an edited SQL query
  • chatAskEdited: Pre-set an edited natural language question

Event Callbacks​

  • handleChatResponse(response): Called when a chat response is received
  • handleReset(): Called when the chat is reset
  • handleEditChat(uuid1, uuid2): Called when a chat message is edited
  • onQueryProcessed(): Called when a query has been processed

iFrame-Specific Options​

Additional options available when using the iFrame embed method:

  • width: Set the iframe width (default: '100%')
  • height: Set the iframe height (default: '600px')
  • position: Set the iframe position (default: 'relative')
  • containerStyles: Additional styles for the iframe container

For detailed configuration options and examples, visit our example repository.

Getting Started​

  1. Complete the database setup and user configuration in the Waii UI
  2. Choose your integration method based on your technical requirements
  3. Install the widget using npm or include it via CDN
  4. Configure the required API credentials
  5. Customize the appearance and behavior as needed

For implementation examples and detailed configuration options, refer to our example repository.

Support​

For technical support or feature requests, contact the Waii support team. We provide assistance with implementation and can help determine the best integration method for your specific use case.