Back to overview
Embed Widgets
Place widgets from your website as embeds on external domains. Manage widget slots and configure allowed domains.
What are Embed Widgets?
Embed Widgets allow you to place certain parts of your website as standalone widgets on external websites. Think of a reviews widget on a partner site, a booking form on an external landing page, or your chatbot on a partner portal.
Available widgets for embedding:
• AI Voice Agent — Voice widget for customer contact
• Chatbot — AI chat widget with conversation history and forward-to-support
• Reviews — Ratings and stars
• Menu — Categories, items and allergens
• Bookings — Schedule appointments
• Reservations — Book tables
Each widget runs in a secure, isolated container (Shadow DOM) that does not interfere with the host website's styles.
Widget slots
Each widget activation consumes one widget slot, regardless of whether it's on your own site or as an embed on an external domain.
Slot limits per plan:
• Starter: 5 slots
• Professional: 15 slots
• Agency: 100 slots
Need more slots? Upgrade to a higher plan. No separate slot packages are available.
Tips
- View your current slot usage via CMS → Embed Widgets.
- Deactivate unused widgets to free up slots.
Activating an embed
Go to CMS → Embed Widgets and follow these steps:
1. Click 'Add Widget'
2. Choose the widget type (e.g. Reviews, Booking)
3. Choose target type: own site or external domain
4. For external domain: enter the full domain (e.g. https://partnersite.com)
5. Click 'Activate'
The system validates the domain (HTTPS required, no private IPs) and activates the widget.
Tips
- You can configure up to 20 allowed domains per site.
- Only HTTPS domains are allowed for embedding.
Note
- Make sure the domain exactly matches where you place the widget. An incorrect domain will block the widget.
Generating embed code
After activation, generate the embed code:
1. Click the code icon next to an active embed
2. Copy the script snippet
3. Paste it into the HTML of the external website
Example:
```html
<script src="https://widgets.your-img-cdn.com/sdk.js"
data-site="YOUR_SITE_ID"
data-widget="reviews"
data-lang="en"></script>
```
The widget loads automatically and displays where you place the script.
Tips
- You can set the language via data-lang (nl, en, de, fr, es).
- The widget automatically adapts to the width of its container.
Security
Embed Widgets are secured with multiple layers:
• Domain validation — Only configured domains can load the widget
• Origin-bound tokens — Short-lived JWT tokens bound to site, widget and domain
• Rate limiting — Maximum 60 requests per site per minute, 20 per IP per minute
• CSP frame-ancestors — Browser protection blocking embedding on unauthorized domains
• Shadow DOM isolation — Widget code and styles are isolated from the host page
Note
- Remove unused domains from your configuration to prevent abuse.
- Don't share your embed code publicly — although the security is domain-bound, it's better to only provide the code to trusted partners.
Deactivating an embed
Go to CMS → Embed Widgets:
1. Click the trash icon next to the embed you want to remove
2. Confirm the deactivation
The widget immediately stops working on the external domain and the slot is freed.
Tips
- After deactivation, the widget will no longer load, even if the script is still on the external site.
Installation per platform
Below are instructions for adding the embed script on each website platform.
WordPress (classic or block editor):
1. Go to the page where you want the widget
2. Add a 'Custom HTML' block (Gutenberg) or switch to the text editor
3. Paste the embed script
4. Save and publish
Elementor:
1. Open the page in Elementor
2. Drag the 'HTML' widget to the desired position
3. Paste the embed script in the HTML field
4. Click 'Update'
Oxygen Builder:
1. Open the page in Oxygen
2. Add a 'Code Block' component
3. Select the 'HTML' or 'Full Code' tab
4. Paste the embed script
5. Save
Webflow:
1. Add an 'Embed' element to the page
2. Paste the embed script in the code field
3. Publish the site
Squarespace:
1. Add a 'Code' block to the page
2. Paste the embed script
3. Save and publish
Wix:
1. Click 'Add' (+) → 'Embed code' → 'Custom embed'
2. Click 'Enter code'
3. Paste the embed script
4. Position the element where you want it
Shopify:
1. Go to Online Store → Themes → 'Edit code'
2. Open the template file for the desired page (e.g. `page.liquid`)
3. Paste the embed script at the desired position
4. Save
Static HTML site:
Paste the embed script directly in the `<body>` of your HTML file where you want the widget to appear.
Tips
- The script can go anywhere in the <body> — the widget appears at that exact position (except Voice Agent and Chatbot, which float bottom-right).
- You do NOT need to add any extra CSS or JavaScript. The script loads everything automatically.
- Always test on a staging/preview environment before publishing.
Note
- Do NOT place the script in the <head> — it needs a visible element and must be in the <body>.
- Some platforms (like Wix) cache pages aggressively. After adding the script, it may take a moment for the widget to become visible.
What each widget shows & styling
Per widget:
• Voice Agent — A floating call button at the bottom-right of the page. When clicked, a call panel opens with microphone, mute, and hang-up buttons. The visitor starts a WebRTC voice connection with the AI Phone Agent directly from the browser (no phone number needed).
• Chatbot — A floating chat button at the bottom-right. When clicked, a chat window opens with message history, markdown support, and optional forward-to-support via email. No login required for visitors — works based on siteId. Supports email capture, welcome message and 5 languages.
• Reviews — Average score with stars + list of individual reviews (name, date, text, stars).
• Menu — Categories with items, prices and allergen information. Includes search and filter functionality.
• Booking — A step-by-step flow: choose date → choose time → fill in details → confirmation.
• Reservation — Similar to booking but for restaurants: choose number of guests + date → choose time → fill in details → confirmation.
Styling:
Each widget runs in a Shadow DOM container. This means:
• CSS from the external website does NOT affect the widget
• The widget does NOT affect the external website
• You CANNOT apply custom CSS to the internal elements of the widget
Limited customization via data attributes:
• `data-theme="light"` or `data-theme="dark"` — switch between light and dark theme
• `data-lang="en"` — set the language (nl, en, de, fr, es)
The widget automatically uses the brand colors configured in your OptimoCMS site settings.
Tips
- Voice Agent and Chatbot always float at the bottom-right, regardless of where you place the script on the page.
- The other widgets (reviews, menu, booking, reservation) render inline at the position of the script.
- The Chatbot automatically fetches your chatbot settings (welcome message, color, name) from the CMS.
- The Shadow DOM isolation prevents conflicts with your existing theme or CSS.