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
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:
Property | Type | Description |
---|---|---|
event_type | String | Always "service_area_check" |
territory_id | String | Unique identifier for the service territory |
territory_name | String | Name of the service territory |
within_service_area | Boolean | Whether the location is within your service area |
customer_location | Object | Details about the customer's location |
customer_location.formatted | String | Full formatted address |
customer_location.line_1 | String | Street address |
customer_location.city | String | City name |
customer_location.state | String | State or province name |
customer_location.postal_code | String | ZIP or postal code |
customer_location.lat | Number | Latitude coordinate |
customer_location.lng | Number | Longitude coordinate |
timeslot_selected
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:
Property | Type | Description |
---|---|---|
event_type | String | Always "timeslot_selected" |
date | String | The selected date in YYYY-MM-DD format |
slot_display | String | Formatted time range for display |
service_selected
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:
Property | Type | Description |
---|---|---|
event_type | String | Always "service_selected" |
service_name | String | Name of the selected service |
service_id | String | Unique identifier for the service |
base_price | String | Base price of the service |
category_selected
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:
Property | Type | Description |
---|---|---|
event_type | String | Always "category_selected" |
category_name | String | Name of the selected category |
category_id | String | Unique identifier for the category |
submission
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:
Property | Type | Description |
---|---|---|
event_type | String | Always "submission" |
service_name | String | Name of the booked service |
service_ids | String | Unique identifier(s) for the service(s) |
booking_flow | String | Type of booking flow used |
recurring_frequency | String or null | Frequency for recurring bookings, if applicable |
coupon_code | String or null | Applied coupon code, if any |
territory_name | String | Name of the service territory |
booking_total | Number | Total 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.
Updated 1 day ago