Widget Configuration Guide
By Alex Bisbe. April 2026.
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 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:
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:
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.
This allows you to:
Test agent selection and language switching.
Verify styling and brand consistency.
Confirm legal consent flows work correctly.
Make a real VoIP test call to verify agent behavior.
Quick Setup Checklist
Create and activate your agents in Agent Studio (set language, voice, goal, script, objections).
Navigate to Campaign → Widget.
Select agents and set the display order per language.
Choose your variant (Bubble or Compact).
Upload your logo and set your brand colors.
Add your Privacy Policy and Terms and Conditions URLs. Enable "Require terms acceptance" if needed.
Customize widget texts for each language.
Preview and test the widget in the configuration panel.
Copy the embed script and paste it into your website HTML.
Go live.
Related Articles
New VoiceB Web Widget & WebRTC VoIP Channel — Product overview, channel strategy, and SuperVoice vs. phone-based agents.
Call Transfer: Redirect Calls to a Human Agent — How to set up VoIP-to-PSTN handoff for hybrid AI + human workflows.
© 2026 Sekondary S.L. DBA VoiceB.ai. All rights reserved.
Last updated
Was this helpful?