> ## 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.

# Embed Voice and Chat Widgets on Your Website

> Embed AI voice and chat widgets on your website. Add conversational AI to any page with a simple script tag.

Add your agent to any website. Users talk or chat with the agent directly in the browser — no phone number needed.

**What you'll learn:** Quick setup, embedding code, and platform-specific installation.

<Tip>
  The widget works on any HTTPS website. Voice calls require HTTPS; text chat works on HTTP.
</Tip>

***

## Quick start

<Steps>
  <Step title="Create web integration">
    Go to **Agents** → Select your agent → **Web Integrations** → **Add Integration**
  </Step>

  <Step title="Add allowed origins">
    Add your website domains: `https://example.com`, `https://www.example.com`
  </Step>

  <Step title="Enable features">
    Toggle AllowWebCall, AllowWebChat, or both
  </Step>

  <Step title="Generate token">
    Save → **Authentication** tab → **Generate Token** → Copy immediately (shown once)
  </Step>

  <Step title="Embed on site">
    Add before the closing `</body>` tag:

    ```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"
    ></blackbox-agent>
    <script src="https://blackbox.dasha.ai/widget/blackbox-widget-v3.min.js" defer></script>
    ```
  </Step>
</Steps>

That's it. The widget appears on your site, ready for voice and chat conversations.

***

## Platform-specific installation

<Card title="Widget Configuration" icon="gear" href="/docs/deploy/widget-configuration">
  Complete guide: React, Next.js, WordPress, attributes, features, and security
</Card>

***

## Widget attributes

| Attribute    | Required | Description                                            |
| ------------ | -------- | ------------------------------------------------------ |
| `server-url` | Yes      | Dasha BlackBox API server                              |
| `token`      | Yes      | Web integration token                                  |
| `position`   | No       | `bottom-right`, `bottom-left`, `top-right`, `top-left` |
| `theme`      | No       | `light` or `dark`                                      |

<Card title="Widget Customization" icon="palette" href="/docs/deploy/widget-customization">
  Complete guide: CSS variables, JavaScript API, and branding
</Card>

***

## Security

<Warning>
  **Never use `*` wildcard** for all origins in production. This allows anyone to use your widget.
</Warning>

Configure specific domains in the Origins tab:

* `https://example.com` — exact match
* `https://*.example.com` — all subdomains
* `http://localhost:3000` — local development

<Card title="Configuring Webhooks" icon="shield" href="/docs/webhooks-and-events/configuring-webhooks">
  Complete webhook configuration and security guide
</Card>

***

## Troubleshooting

| Issue                | Solution                                         |
| -------------------- | ------------------------------------------------ |
| Widget not loading   | Check token is correct, integration is enabled   |
| Origin blocked error | Add exact domain to origins (include `https://`) |
| Voice not working    | Verify site uses HTTPS, check mic permission     |

<Card title="Common Issues" icon="circle-question" href="/docs/troubleshooting/common-issues">
  Complete troubleshooting guide
</Card>

***

## What's next

<CardGroup cols={2}>
  <Card title="Widget Configuration" icon="gear" href="/docs/deploy/widget-configuration">
    Configure features, tokens, and security
  </Card>

  <Card title="Widget Customization" icon="palette" href="/docs/deploy/widget-customization">
    Customize styling and behavior
  </Card>

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

  <Card title="Call History" icon="chart-line" href="/docs/monitor/call-history">
    Track widget usage
  </Card>
</CardGroup>