Learn how to configure, customize and embed the FlexBookz booking widget on your website or WordPress site for seamless customer bookings.
Was this documentation helpful? Let us know!
The Booking Widget in FlexBookz is a flexible, brandable component that lets customers book appointments directly from your website. It connects to your FlexBookz account, respects staff schedules and service availability, and can be embedded in multiple formats (popup dialog, floating bubble, inline iframe) or installed through a WordPress plugin. This documentation explains how the widget works, how to configure and embed it, practical use cases, and troubleshooting tips to ensure a smooth booking experience for your customers.
The widget communicates with FlexBookz using an authentication API key and a list of permitted domains. When a visitor opens the widget it requests real-time availability for services and staff, displays the booking flow you configured, and submits bookings back to your FlexBookz calendar. You can customize appearance, language, booking behavior and form fields to match your business needs.
The widget supports multiple display modes:
Dialog — a triggered popup that opens when a visitor clicks a button or link.
Bubble — a persistent floating action button typically positioned bottom-right.
Iframe — embedded inline where you want the full booking UI to appear on a page.
WordPress plugin — installable plugin with Gutenberg blocks and shortcodes.
Go to Settings > Booking Widget in your FlexBookz dashboard.
Locate the API key. Copy it or click Regenerate to create a new key.
Keep the key secure — treat it like a password. If leaked, regenerate and update your embeds immediately.
Under Permitted Domains, add each website URL that will host the widget (for example https://example.com or https://book.example.com).
Click Add to save each domain. This whitelisting prevents the widget from being used on unauthorized sites.
Open the Theme Builder tab in the widget settings.
Select a base template (for example Modern & Minimal or Classic Professional).
Adjust colors, fonts, button appearance and iconography to match your brand.
Use the Live Preview to test adjustments across desktop and mobile breakpoints.
Open the Content tab to set languages, labels and inline help texts.
Under Behavior configure the booking flow and form fields. Typical options include:
Skip Staff Selection — hide staff choice and auto-assign based on availability.
Express Mode — a condensed flow for returning customers with fewer required fields.
Combine Date & Time — present date and time selection in one step.
Set validation rules, required fields, and opt-in toggles for marketing communications.
Choose one of the embedding options and add the supplied code to your site:
Dialog (triggered popup)
Place a trigger element on your page and include the main script once (typically in <head> or before </body>):
<!-- FlexBookz Widget Script -->
<script src="https://cdn.flexbookz.com/widget.js" defer></script>
<!-- Trigger button -->
<button data-flexbookz-trigger="open" data-fb-api-key="YOUR_API_KEY">Book Now</button>
Bubble (floating)
<script src="https://cdn.flexbookz.com/widget.js" defer></script>
<script>
window.FlexBookzWidget && window.FlexBookzWidget.init({
apiKey: 'YOUR_API_KEY',
display: 'bubble',
position: 'bottom-right'
});
</script>
Iframe (inline)
Use an iframe when you want the full booking UI inline on a page:
<iframe src="https://widget.flexbookz.com/embed?apiKey=YOUR_API_KEY"
title="Book an appointment"
style="width:100%;height:800px;border:0;"></iframe>
WordPress Plugin
Install the FlexBookz plugin from the WordPress plugin directory or upload the plugin ZIP.
Activate the plugin and navigate to the FlexBookz settings in WP admin.
Enter your API key, configure display options and add the Gutenberg block or shortcode to any page/post.
Single-location salon: Use Dialog mode on your homepage with Skip Staff Selection to speed up bookings for walk-in-style businesses.
Multi-location spa: Use the iframe on each location page to pre-filter available services and staff per location.
Promotional campaigns: Add a time-limited landing page with the widget in Express Mode to capture bookings quickly during a promotion.
WordPress site owners: Use the plugin and a Gutenberg block to add the widget to service pages or site footer globally.
Tip: Pre-selecting a service or location in the widget URL lets you create direct booking links from email campaigns or social ads.
Always use https on your site to ensure secure widget operation and protect customer data.
Match the widget theme to your brand to increase trust and conversion rates.
Test the booking flow on different devices and browsers to ensure responsiveness and accessibility.
Enable verification cookies or a returning-customer flow to reduce friction for repeat bookings.
Set appropriate buffers and service durations in FlexBookz to prevent double-bookings and allow staff prep time.
Integrate with Google Calendar or your POS to keep schedules and sales synchronized.
Use pre-filled parameters (service, location, staff) in URL links for targeted campaign tracking.
Widget does not load:
Confirm the domain hosting the widget is listed under Permitted Domains.
Ensure the API key entered in the embed code matches the one in FlexBookz.
Open your browser console to check for blocked resources (CORS or mixed-content errors).
Styling conflicts with site CSS:
Clear site caches and CDN caches after updates.
Load the widget in an iframe to isolate styles if conflicts persist.
No services or availability shown:
Verify services and staff are active and assigned to the location in FlexBookz.
Check time-off settings and staff schedules for conflicts.
Bookings not appearing in calendar:
Confirm that booking submission is returning a success response in the network tab.
Ensure notifications and sync integrations (Google Calendar, POS) are configured properly.
If you need hands-on assistance, contact FlexBookz support through your dashboard or schedule a walkthrough with our onboarding team.