> ## Documentation Index
> Fetch the complete documentation index at: https://blackbox.dasha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Widget Security and Features

> Configure web widget security, features, and appearance. Manage tokens, origin restrictions, and feature toggles.

The dashboard provides five configuration tabs: Basic Info, Origins, Authentication, Features, and Test Widget. Complete them in order — some tabs depend on others.

**What you'll learn:** Dashboard tabs walkthrough, origin patterns, token management, feature toggles, and allowed tools.

## Configuration tabs

| Tab                | Purpose                           |
| ------------------ | --------------------------------- |
| **Basic Info**     | Name, description, enabled state  |
| **Origins**        | Domain security (CORS)            |
| **Authentication** | Token generation and management   |
| **Features**       | Capability toggles, allowed tools |
| **Test Widget**    | Live preview, embed code          |

**Complete tabs 1-2 first, save, then return to generate tokens in tab 3.**

***

## Basic settings

### Name and description

Use clear, environment-specific names:

| Do                             | Avoid            |
| ------------------------------ | ---------------- |
| "Production Website Widget"    | "Widget 1"       |
| "Staging - Support Chat"       | "Test"           |
| "Mobile App - Voice Assistant" | "My Integration" |

### Enabled toggle

| State        | Effect                                           |
| ------------ | ------------------------------------------------ |
| **Enabled**  | Widget accepts connections                       |
| **Disabled** | All connections rejected (even with valid token) |

**Disable during maintenance or to immediately stop all widget access.**

***

## Origin restrictions

Protect your widget from unauthorized use by whitelisting allowed domains.

### Add origins

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Origins** tab
    2. Enter domain URL (e.g., `https://example.com`)
    3. Click **Add** or press Enter
    4. Repeat for additional domains
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    await fetch(`https://blackbox.dasha.ai/api/v1/web-integrations/${integrationId}`, {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        origins: [
          'https://example.com',
          'https://www.example.com',
          'https://*.example.com'
        ]
      })
    });
    ```
  </Tab>
</Tabs>

### Origin patterns

| Pattern                   | Matches                      |
| ------------------------- | ---------------------------- |
| `https://example.com`     | Exact domain only            |
| `https://www.example.com` | www subdomain only           |
| `https://*.example.com`   | All subdomains (not root)    |
| `http://localhost:3000`   | Local dev with specific port |

### Environment patterns

<Tabs>
  <Tab title="Production">
    ```
    https://example.com
    https://www.example.com
    ```
  </Tab>

  <Tab title="Multi-environment">
    ```
    https://example.com
    https://www.example.com
    https://staging.example.com
    http://localhost:3000
    ```
  </Tab>

  <Tab title="All subdomains">
    ```
    https://example.com
    https://*.example.com
    ```
  </Tab>
</Tabs>

<Warning>
  **Never use `*`** to allow all origins in production. Remove `localhost` origins before deploying to production.
</Warning>

***

## Authentication

Generate and manage access tokens for widget authentication.

### Generate token

<Steps>
  <Step title="Save integration first">
    Authentication tab is disabled until integration is saved
  </Step>

  <Step title="Open Authentication tab">
    Edit saved integration → **Authentication** tab
  </Step>

  <Step title="Enter token name">
    Use descriptive name: "Production Website Token"
  </Step>

  <Step title="Generate and copy">
    Click **Generate Token** → Copy immediately (shown once)
  </Step>
</Steps>

### Token security

| Do                             | Avoid                     |
| ------------------------------ | ------------------------- |
| Store in environment variables | Commit to Git             |
| Rotate every 90 days           | Share across integrations |
| Delete compromised tokens      | Reuse deleted tokens      |
| Monitor "Last Used" timestamp  | Use generic names         |

<Accordion title="Store tokens securely">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // .env (never commit)
  BLACKBOX_WIDGET_TOKEN=bb_prod_abc123...

  // .gitignore
  .env
  .env.local
  ```
</Accordion>

### Delete token

1. Click trash icon next to token
2. Confirm deletion
3. Token immediately revoked

<Warning>
  Deleting a token immediately breaks widgets using it. Update your site first.
</Warning>

***

## Feature toggles

Control which capabilities are available in the widget.

### Available features

| Feature                        | Description              | When to enable               |
| ------------------------------ | ------------------------ | ---------------------------- |
| **AllowWebCall**               | Voice calls via WebRTC   | Voice-first support, demos   |
| **AllowWebChat**               | Text chat messages       | Universal (works everywhere) |
| **AllowPhoneCall**             | Phone call option        | When phone backup needed     |
| **SendCallResult**             | Return call data to page | Custom post-call UI          |
| **SendToolCallLogs**           | Stream tool execution    | Debugging only               |
| **SendTranscriptForAudioCall** | Real-time transcript     | Accessibility, compliance    |

### Feature combinations

<Tabs>
  <Tab title="Voice only">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    features: [
      { name: 'AllowWebCall', enabled: true },
      { name: 'SendTranscriptForAudioCall', enabled: true }
    ]
    ```

    Best for: Sales calls, support requiring voice
  </Tab>

  <Tab title="Chat only">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    features: [
      { name: 'AllowWebChat', enabled: true }
    ]
    ```

    Best for: FAQ bots, low-bandwidth users
  </Tab>

  <Tab title="Voice + Chat">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    features: [
      { name: 'AllowWebCall', enabled: true },
      { name: 'AllowWebChat', enabled: true },
      { name: 'SendCallResult', enabled: true }
    ]
    ```

    Best for: Maximum flexibility
  </Tab>
</Tabs>

### Allowed tools

Select which agent tools can be called via widget:

1. Go to **Features** tab
2. Click **Allowed Tools** dropdown
3. Select tools from agent and MCP sources
4. Only selected tools accessible from widget

<Tip>
  Only expose safe, public-facing tools. Avoid administrative or sensitive operations.
</Tip>

***

## Appearance

Configure visual presentation in the **Test Widget** tab.

### Theme

| Theme   | Use case                          |
| ------- | --------------------------------- |
| `light` | Light-colored websites            |
| `dark`  | Dark-mode websites, tech products |

### Position

| Position       | Best for                         |
| -------------- | -------------------------------- |
| `bottom-right` | Most websites (familiar pattern) |
| `bottom-left`  | Right side has other elements    |
| `top-right`    | Dashboard interfaces             |

<Accordion title="Embed code generation">
  The Test Widget tab generates ready-to-use code:

  ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <blackbox-agent
    server-url="https://blackbox.dasha.ai"
    token="YOUR_TOKEN"
    position="bottom-right"
    theme="dark"
    skip-discovery
    data-config='{"features":["AllowWebCall","AllowWebChat"]}'
  ></blackbox-agent>

  <script src="https://blackbox.dasha.ai/widget/blackbox-widget-v3.min.js" defer></script>
  ```
</Accordion>

***

<Accordion title="API configuration">
  Update configuration programmatically:

  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  await fetch(`https://blackbox.dasha.ai/api/v1/web-integrations/${integrationId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Production Website Widget',
      enabled: true,
      origins: ['https://example.com', 'https://www.example.com'],
      features: [
        { name: 'AllowWebCall', enabled: true },
        { name: 'AllowWebChat', enabled: true },
        { name: 'SendCallResult', enabled: true }
      ],
      tools: ['check_order_status', 'schedule_callback'],
      widgetAppearance: {
        theme: 'dark',
        position: 'bottom-right'
      }
    })
  });
  ```
</Accordion>

***

## Troubleshooting

<Accordion title="Token authentication failing">
  **Causes**: Token deleted, integration disabled, token malformed

  **Solutions**:

  1. Verify token exists in Authentication tab
  2. Check integration enabled toggle
  3. Re-copy token (no extra spaces)
  4. Generate new token if needed
</Accordion>

<Accordion title="CORS errors in console">
  **Causes**: Domain not in origins, protocol mismatch

  **Solutions**:

  1. Add exact origin to allowed list
  2. Check `http://` vs `https://`
  3. Include port if non-standard
  4. Add both www and non-www
</Accordion>

<Accordion title="Features not working">
  **Causes**: Feature disabled, wrong data-config

  **Solutions**:

  1. Enable feature in Features tab
  2. Check data-config JSON syntax
  3. Try without `skip-discovery`
  4. Verify feature appears in Test Widget
</Accordion>

<Accordion title="Tools not executing">
  **Causes**: Tool not in allowed list, tool deleted

  **Solutions**:

  1. Add tool to Allowed Tools
  2. Verify tool exists in agent config
  3. Check MCP server connectivity
  4. Review tool error in Call Inspector
</Accordion>

***

## What's next

<CardGroup cols={2}>
  <Card title="Widget Customization" icon="palette" href="/docs/deploy/widget-customization">
    Advanced styling and JavaScript API
  </Card>

  <Card title="Web Widget Embedding" icon="code" href="/docs/deploy/web-widget-embedding">
    Platform-specific installation
  </Card>

  <Card title="Production Checklist" icon="clipboard-check" href="/docs/deploy/production-checklist">
    Pre-launch verification
  </Card>

  <Card title="Webhook Events" icon="bell" href="/docs/webhooks-and-events/webhook-events">
    Handle widget events server-side
  </Card>
</CardGroup>