Widget Setup Guide

1Create and Save a Query

First, create a query in the DataWhisper chat interface:

1. Navigate to your workspace and select a database
2. Ask your question in natural language (e.g., "Show monthly revenue")
3. Click the Save Query button
4. Give it a name and optional description

2Make the Query Public

Enable public access for the saved query:

1. Go to Saved Queries in your workspace
2. Find your query and click the settings/edit button
3. Toggle Make Public to enable embedding
4. Copy the generated embed token

3Embed Using iframe

Add the widget to your website using an iframe:

<iframe
  src="https://datawhisper.sh/embed/your-embed-token-here"
  width="100%"
  height="400"
  frameborder="0"
  style="border-radius: 8px; border: 1px solid #1e3a5f;"
></iframe>

Responsive Embed Example

For responsive layouts, wrap the iframe in a container:

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe
    src="https://datawhisper.sh/embed/your-embed-token-here"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none; border-radius: 8px;"
    allowfullscreen
  ></iframe>
</div>

1Enable Database Embedding

Enable embedding for your database:

1. Go to your Workspace > Databases
2. Click on your database settings
3. Navigate to the Embed Settings tab
4. Toggle Enable Embedding
5. Copy the generated Embed Token

2API Integration

Use the widget API to execute queries. All requests require theX-Embed-Token header.

curl -X GET "https://datawhisper.sh/api/v1/widget/config" \
  -H "X-Embed-Token: your-database-embed-token"

curl -X POST "https://datawhisper.sh/api/v1/widget/query" \
  -H "X-Embed-Token: your-database-embed-token" \
  -H "Content-Type: application/json" \
  -d '{"question": "Show me total sales by month"}'

3JavaScript Integration Example

const EMBED_TOKEN = "your-database-embed-token";
const API_URL = "https://datawhisper.sh/api/v1";

async function askQuestion(question) {
  const response = await fetch(`${API_URL}/widget/query`, {
    method: "POST",
    headers: {
      "X-Embed-Token": EMBED_TOKEN,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ question }),
  });

  if (!response.ok) {
    throw new Error("Query failed");
  }

  return response.json();
}

// Usage
const result = await askQuestion("What are the top 10 customers?");
console.log(result.data);       // Query results
console.log(result.sql);        // Generated SQL
console.log(result.visualization); // Suggested chart type

Response Format

{
  "sql": "SELECT customer_name, SUM(amount) as total FROM orders GROUP BY 1 ORDER BY 2 DESC LIMIT 10",
  "data": [
    {"customer_name": "Acme Corp", "total": 150000},
    {"customer_name": "Widget Inc", "total": 125000}
  ],
  "columns": ["customer_name", "total"],
  "row_count": 10,
  "execution_time_ms": 45.2,
  "visualization": {
    "type": "bar_chart",
    "config": {
      "x_axis": "customer_name",
      "y_axis": "total"
    }
  }
}

Suggested Queries

Configure suggested queries to help users get started:

1. Go to Database > Embed Settings
2. Add suggested queries in the Suggested Queries section
3. These will appear as quick-start options in the widget

Visualization Types

The widget automatically suggests appropriate visualizations:

iframe URL Parameters

Customize the embed appearance with URL parameters:

Best Practices

• Use a dedicated database user with minimal permissions
• Limit access to only the tables and columns needed
• Enable query timeout to prevent long-running queries
• Regularly rotate embed tokens for sensitive data
• Monitor the query history for unusual patterns

Revoking Access

To revoke embed access:

1. For saved queries: Toggle off Make Public
2. For database embedding: Toggle off Enable Embedding or regenerate the token