# Widget Configuration Guide
### Overview
The VoiceB Web Widget is the primary way to deploy AI voice agents on your website or landing page. It connects visitors directly to your SuperVoice agents via WebRTC VoIP β no phone number required, no app to install, no friction.
This guide covers every configuration option available in the **Widget** section of the VoiceB platform (`app.voiceb.ai β Campaign β Widget`).
> **New to the VoiceB Widget?** Start with [New VoiceB Web Widget & WebRTC VoIP Channel](https://docs.voiceb.ai/new-voiceb-web-widget-and-webrtc-voip-channel) for the product overview and channel strategy. This article focuses on the configuration details.
***
### Installation
Deploying the widget requires a single line of JavaScript. Copy the embed snippet from your Widget Configuration page and paste it into your website's HTML:
```html
```
Each widget has a unique `data-widget-id`. You'll find your specific snippet in the **Setup** section of the Widget Configuration page.
The widget works on any website, landing page, or web application β anywhere you can add a script tag.
***
### Widget Configuration Options
#### 1. Select Agents (Multi-Agent Support)
The widget supports **multiple agents simultaneously**. You can connect as many agents as you need to a single widget deployment.
In the **Select Agents** section, check the agents you want to make available through the widget. Each agent is identified by name and a language flag indicating their configured language (e.g., πΊπΈ for English, πͺπΈ for Spanish, π§π· for Portuguese).
**Key capability:** The widget operates at the **campaign level**, meaning one widget deployment can handle multiple agents across different languages and use cases. This makes it ideal for multi-market websites and landing pages serving diverse audiences.
***
#### 2. Agent Display Order
Once agents are selected, you can control the order in which they appear to the visitor by dragging and dropping agent cards in the **Agent Display Order** section.
Agents are organized **per language**. For example, if your widget serves English (EN-US) and Spanish (ES) visitors, you'll see two separate columns β one for each language β where you can independently set the display priority for agents within that language group.
***
#### 3. Variant (Bubble vs. Compact)
Choose how the widget appears on your page:
* **Bubble** β Displays a small floating bubble in the corner of the screen showing just your logo (or the default VoiceB icon). Minimal footprint, maximum discretion. When clicked, the widget expands to show the full agent interface.
* **Compact** β Shows a slightly larger floating element with your logo and a welcome message (e.g., "Talk to SuperVoice"). More visible and explicit, which can drive higher engagement on high-intent pages.
Both variants include the VoiceB logo icon alongside a phone icon, and display "Powered by voiceb.ai" at the bottom.
**Recommendation:** Use **Bubble** on pages where the widget supplements the experience (e.g., product pages, blog). Use **Compact** on conversion-critical pages (e.g., pricing, plan selectors, checkout flows) where you want to maximize voice engagement.
***
#### 4. Language Selector
When your widget includes agents in more than one language, the widget automatically displays a **language selector** (e.g., "EN-US | ES") so visitors can choose their preferred language.
You can control language display behavior in **Language Display**:
* **Show language badges** β Displays language flags next to agent names.
* **Always show language badges (even with a single language)** β Forces the language selector to appear even if all agents share the same language. Useful for consistency across deployments.
The **Default Language** setting determines which language tab is pre-selected when the widget loads.
***
#### 5. Logo
Customize the widget icon by providing a URL to your own logo image. The recommended size is **64Γ64 pixels**. If the URL is empty or fails to load, the default VoiceB icon will be used.
You can also enable **"Hide icon when URL is empty or fails to load"** to suppress the icon entirely in case of loading errors, rather than falling back to the VoiceB default.
***
#### 6. Privacy Policy & Terms and Conditions (Compliance)
The widget supports **full regulatory compliance** for data privacy and consent collection:
* **Privacy Policy URL** β Link to your Privacy Policy page. When set, a "I accept the Privacy Policy" checkbox appears in the widget.
* **Terms and Conditions URL** β Link to your Terms and Conditions page. When set, this is shown alongside the Privacy Policy link.
* **Terms Required** β When enabled ("Require terms acceptance"), the visitor **must** check the consent box before initiating a call.
**Compliance storage:** When a visitor accepts the Privacy Policy and/or Terms and Conditions, VoiceB stores the consent record β including the document content β **up to 50 MB per document** in the database. This ensures you have a complete audit trail of what each visitor consented to, and which version of the documents was in effect at the time of consent. This is critical for GDPR, LOPDGDD, and other regulatory frameworks.
> **Important:** If neither a Privacy Policy URL nor a Terms URL is set, no checkbox or legal link will be shown in the widget.
***
#### 7. Widget Styles (Full Visual Customization)
The widget is fully customizable to match your brand identity. Every visual element can be adjusted.
**Surface Palette**
Control the core appearance of the widget:
* **Background** β Main background color of the widget panel.
* **Background Hover** β Background color on hover states.
* **Border** β Border color for the widget container.
* **Muted** β Color for secondary/muted text and elements.
* **Foreground** β Primary text color.
**Brand Palette**
Set your brand colors for interactive elements:
* **Primary** β Main brand color used for buttons and CTAs (e.g., the "Talk now" button).
* **Primary Hover** β Hover state for primary elements.
* **Primary Active** β Active/pressed state for primary elements.
* **Contrast** β Text color used on top of primary-colored elements (ensures readability).
**Metrics (Sizing & Spacing)**
Fine-tune dimensions, spacing, and corner radius:
| Setting | Description | Default |
| ------------------ | -------------------------------------------------- | ------- |
| Horizontal Padding | Left/right padding inside the widget | 20 |
| Vertical Padding | Top/bottom padding inside the widget | 20 |
| Main Radius | Corner radius of the main widget panel | 16 |
| Bubble Radius | Corner radius of the floating bubble | 50 |
| Bubble Padding | Internal padding of the bubble | 6 |
| Button Radius | Corner radius of CTA buttons | 8 |
| Inputs Radius | Corner radius of input fields (e.g., phone number) | 8 |
| Compact Font Size | Font size for the compact variant text | 14 |
| Compact Padding | Padding inside the compact variant | 12 |
| Compact Icon Size | Size of the icon in the compact variant | 36 |
**Toggles**
* **Show agent card borders** β Adds visible borders around individual agent cards.
* **Show language badge borders** β Adds borders around the language selector badges.
* **Show section dividers** β Adds horizontal dividers between widget sections.
***
#### 8. Widget Texts (Per-Language Customization)
Customize all user-facing text in the widget on a per-language basis.
Select the language you want to edit from the **Edit Language** dropdown, then configure:
**General**
* **Title** β The header displayed at the top of the widget (e.g., your company name or a tagline like "Talk to SuperVoice" / "Habla con SuperVoice").
* **Greeting Text** β The welcome message shown in the compact variant or as a subtitle (e.g., "How can we help you?").
**Agent Cards**
For each agent, you can override:
* **Heading** β The title shown on the agent's card.
* **Description** β The description text below the heading.
* **Button Label** β The CTA button text (e.g., "Talk now", "Habla ahora").
* **Alignment** β Left or center alignment for the card content.
***
#### 9. Analytics: Impressions, Clicks & UTM Tracking
The widget automatically tracks:
* **Impressions** β Every time the widget loads on a page, an impression is recorded.
* **Clicks** β Every interaction (opening the widget, clicking "Talk now", clicking "We call you for free") is tracked.
* **UTM parameters** β The widget captures UTM tags (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`) from the page URL. This connects every voice conversation back to the marketing campaign that drove the visit, enabling closed-loop attribution from ad spend to voice conversion.
This data feeds into your VoiceB Dashboard alongside call outcomes, durations, and conversion rates.
***
### Preview & Testing
You can **preview and fully test the widget** directly from the Widget Configuration page β no need to deploy it to a live site first. The widget preview panel appears on the right side of the configuration screen and updates in real time as you change settings.
