Configure Widget Security and Features

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

Dashboard
API

Go to Origins tab
Enter domain URL (e.g., https://example.com)
Click Add or press Enter
Repeat for additional domains

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'
    ]
  })
});

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

Production
Multi-environment
All subdomains

https://example.com
https://www.example.com

https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000

https://example.com
https://*.example.com

Never use * to allow all origins in production. Remove localhost origins before deploying to production.

Authentication

Generate and manage access tokens for widget authentication.

Generate token

Save integration first

Authentication tab is disabled until integration is saved

Open Authentication tab

Edit saved integration → Authentication tab

Enter token name

Use descriptive name: “Production Website Token”

Generate and copy

Click Generate Token → Copy immediately (shown once)

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

Store tokens securely

// .env (never commit)
BLACKBOX_WIDGET_TOKEN=bb_prod_abc123...

// .gitignore
.env
.env.local

Delete token

Click trash icon next to token
Confirm deletion
Token immediately revoked

Deleting a token immediately breaks widgets using it. Update your site first.

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

Voice only
Chat only
Voice + Chat

features: [
  { name: 'AllowWebCall', enabled: true },
  { name: 'SendTranscriptForAudioCall', enabled: true }
]

Best for: Sales calls, support requiring voice

features: [
  { name: 'AllowWebChat', enabled: true }
]

Best for: FAQ bots, low-bandwidth users

features: [
  { name: 'AllowWebCall', enabled: true },
  { name: 'AllowWebChat', enabled: true },
  { name: 'SendCallResult', enabled: true }
]

Best for: Maximum flexibility

Allowed tools

Select which agent tools can be called via widget:

Go to Features tab
Click Allowed Tools dropdown
Select tools from agent and MCP sources
Only selected tools accessible from widget

Only expose safe, public-facing tools. Avoid administrative or sensitive operations.

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

Embed code generation

The Test Widget tab generates ready-to-use code:

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

API configuration

Update configuration programmatically:

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'
    }
  })
});

Troubleshooting

Token authentication failing

Causes: Token deleted, integration disabled, token malformedSolutions:

Verify token exists in Authentication tab
Check integration enabled toggle
Re-copy token (no extra spaces)
Generate new token if needed

CORS errors in console

Causes: Domain not in origins, protocol mismatchSolutions:

Add exact origin to allowed list
Check http:// vs https://
Include port if non-standard
Add both www and non-www

Features not working

Causes: Feature disabled, wrong data-configSolutions:

Enable feature in Features tab
Check data-config JSON syntax
Try without skip-discovery
Verify feature appears in Test Widget

Tools not executing

Causes: Tool not in allowed list, tool deletedSolutions:

Add tool to Allowed Tools
Verify tool exists in agent config
Check MCP server connectivity
Review tool error in Call Inspector

What’s next

Widget Customization

Advanced styling and JavaScript API

Web Widget Embedding

Platform-specific installation

Production Checklist

Pre-launch verification

Webhook Events

Handle widget events server-side

Introduction

Create

Test

Deploy

Monitor

Advanced Features

Troubleshooting

Configuration tabs

Basic settings

Name and description

Enabled toggle

Origin restrictions

Add origins

Origin patterns

Environment patterns

Authentication

Generate token

Token security

Delete token

Feature toggles

Available features

Feature combinations

Allowed tools

Appearance

Theme

Position

Troubleshooting

What’s next

Widget Customization

Web Widget Embedding

Production Checklist

Webhook Events

​Configuration tabs

​Basic settings

​Name and description

​Enabled toggle

​Origin restrictions

​Add origins

​Origin patterns

​Environment patterns

​Authentication

​Generate token

​Token security

​Delete token

​Feature toggles

​Available features

​Feature combinations

​Allowed tools

​Appearance

​Theme

​Position

​Troubleshooting

​What’s next

Widget Customization

Web Widget Embedding

Production Checklist

Webhook Events

Configuration tabs

Basic settings

Name and description

Enabled toggle

Origin restrictions

Add origins

Origin patterns

Environment patterns

Authentication

Generate token

Token security

Delete token

Feature toggles

Available features

Feature combinations

Allowed tools

Appearance

Theme

Position

Troubleshooting

What’s next