Widget Events

Use JavaScript to track and respond to customer actions in your embedded booking widget

Overview

Zenbooker.js provides a client-side event system that lets you listen for specific user actions that occur within the booking form embedded on your webpage. You can use these events to automatically trigger analytics tracking, marketing conversions, dynamic content changes, or other front-end actions based on how customers interact with your booking widget.

You can listen for events on any page where you've embedded the Zenbooker booking widget.

Getting started

To listen for Zenbooker widget events, use the Zenbooker.on() method with the following syntax:

Zenbooker.on(event_type, callback_function);

For example:

Zenbooker.on("service_selected", function(event) {
    // Your code to run when this event occurs
    console.log("Event triggered:", event);
});

Widget events

The widget emits events during the booking flow. All events have a payload object that includes an event_type property identifying which event was triggered.

service_area_check

Triggered when a customer's location is checked against your service areas.

Zenbooker.on("service_area_check", function(event) {
    console.log("The service area check was triggered.", event);
});

Example payload:

{
    "event_type": "service_area_check",
    "territory_id": "1586239489452x571449227260704600",
    "territory_name": "Silver Spring",
    "within_service_area": true,
    "customer_location": {
        "formatted": "9128 Walden Rd, Silver Spring, MD 20901, USA",
        "line_1": "9128 Walden Road",
        "city": "Silver Spring",
        "state": "Maryland",
        "postal_code": "20901",
        "lat": 39.0071767,
        "lng": -77.0055483
    }
}

Payload properties:

PropertyTypeDescription
event_typeStringAlways "service_area_check"
territory_idStringUnique identifier for the service territory
territory_nameStringName of the service territory
within_service_areaBooleanWhether the location is within your service area
customer_locationObjectDetails about the customer's location
customer_location.formattedStringFull formatted address
customer_location.line_1StringStreet address
customer_location.cityStringCity name
customer_location.stateStringState or province name
customer_location.postal_codeStringZIP or postal code
customer_location.latNumberLatitude coordinate
customer_location.lngNumberLongitude coordinate

timeslot_selected

Triggered when a customer selects an appointment time slot.

Zenbooker.on("timeslot_selected", function(event) {
    console.log("The timeslot was selected.", event);
});

Example payload:

{
    "event_type": "timeslot_selected",
    "date": "2025-03-11",
    "slot_display": "11:00 AM - 1:00 PM"
}

Payload properties:

PropertyTypeDescription
event_typeStringAlways "timeslot_selected"
dateStringThe selected date in YYYY-MM-DD format
slot_displayStringFormatted time range for display

service_selected

Triggered when a customer selects a specific service.

Zenbooker.on("service_selected", function(event) {
    console.log("The service was selected.", event);
});

Example payload:

{
    "event_type": "service_selected",
    "service_name": "Commercial Junk Removal",
    "service_id": "1612244444330x694110863820980500",
    "base_price": "70.50"
}

Payload properties:

PropertyTypeDescription
event_typeStringAlways "service_selected"
service_nameStringName of the selected service
service_idStringUnique identifier for the service
base_priceStringBase price of the service

category_selected

Triggered when a customer selects a service category.

Zenbooker.on("category_selected", function(event) {
    console.log("The category was selected.", event);
});

Example payload:

{
    "event_type": "category_selected",
    "category_name": "Junk Removal",
    "category_id": "1608274768986x536105891288580100"
}

Payload properties:

PropertyTypeDescription
event_typeStringAlways "category_selected"
category_nameStringName of the selected category
category_idStringUnique identifier for the category

submission

Triggered when a customer completes and confirms their booking.

Zenbooker.on("submission", function(event) {
    console.log("The booking was confirmed.", event);
});

Example payload:

{
    "event_type": "submission",
    "service_name": "Junk Removal",
    "service_ids": "1704222609331x592420065365196800",
    "booking_flow": "booking",
    "recurring_frequency": null,
    "coupon_code": null,
    "territory_name": "Silver Spring",
    "booking_total": 132.37
}

Payload properties:

PropertyTypeDescription
event_typeStringAlways "submission"
service_nameStringName of the booked service
service_idsStringUnique identifier(s) for the service(s)
booking_flowStringType of booking flow used
recurring_frequencyString or nullFrequency for recurring bookings, if applicable
coupon_codeString or nullApplied coupon code, if any
territory_nameStringName of the service territory
booking_totalNumberTotal booking amount

Example use cases

Track conversions

Send events to analytics platforms when a booking is submitted:

Zenbooker.on("submission", function(event) {
    // Send conversion event to Google Analytics
    gtag('event', 'conversion', {
        'send_to': 'AW-CONVERSION_ID/CONVERSION_LABEL',
        'value': event.booking_total,
        'currency': 'USD'
    });
    
    // Send to Facebook Pixel
    fbq('track', 'Purchase', {
        value: event.booking_total,
        currency: 'USD',
        content_name: event.service_name
    });
});

Display custom offers

Show targeted offers based on service selection:

Zenbooker.on("service_selected", function(event) {
    if (event.service_name.includes("Junk Removal")) {
        // Show special offer for junk removal services
    }
});

Customize by location

Modify the booking experience based on the customer's location:

Zenbooker.on("service_area_check", function(event) {
    if (event.within_service_area) {
        // Show territory-specific information
    } else {
        // redirect customers to a waitlist signup
    }
});


Note: Widget events operate client-side in the browser and are distinct from Zenbooker's server-side webhooks. Use widget events for real-time user interface interactions and webhooks for server-to-server communication.

Troubleshooting

  • Events not firing: Verify that your event listener code runs after Zenbooker.js has loaded on the page.