🚨 If you're using our legacy booking tools, such as Standard or Enterprise widget, you may wish to explore this guide instead.

⚠️ This guide is technical in nature and assumes a basic level of knowledge of HTML and JavaScript.

Our booking tools emit various events that you can listen to with JavaScript code on your website. You can then either forward this data to other systems and/or integrations or even execute functionality on your website based on these events.

The code that you need depends if you are using the embedded version or the popover version of our booking tools; this guide contains code snippets for both versions.

Listener Script

To get started insert the following snippet of code onto the same web page where your booking tools are placed.

Popover Listener Script

Use this script if you are using our booking tools in popover mode. It is designed to prevent your listeners from being registered more than once and handle the scripts being loaded asynchronously.

<script src="https://booking-tools-sdk.appointedd.com/appointedd-booking-tools-sdk-v1.js"></script>
<script language="javascript" type="text/javascript">
  let registered = false;

  function init() {
    if (registered) return;

    // Insert your event listeners in this function.

    window.Appointedd.popovers.on("READY", function() {
      console.log("Appointedd booking tool is ready!");
    });
  }

  if (window.Appointedd) {
    init();
  } else {
    window.addEventListener(
      "appointedd-booking-tools-sdk-v1",
      function(event) {
        if (event.detail.type === "sdk.ready") init();
      }
    );
  }
</script>

Embedded Listener Script

Use this script if you are using our booking tools in embedded mode. It is designed to prevent your listeners from being registered more than once and handle the scripts being loaded asynchronously.

<div id="iFrameContainer"></div>
<script src="https://booking-tools-sdk.appointedd.com/appointedd-booking-tools-sdk-v1.js"></script>
<script language="javascript" type="text/javascript">
  let registered = false;

  function init() {
    if (registered) return;

    const bookingTool = Appointedd.renderWidget("iFrameContainer", {
      widgetId: "[YOUR_WIDGET_ID]"
    });

    bookingTool.on("READY", function() {
      console.log("Appointedd booking tool is ready!");
    });
  }

  if (window.Appointedd) {
    init();
  } else {
    window.addEventListener(
      "appointedd-booking-tools-sdk-v1",
      function(event) {
        if (event.detail.type === "sdk.ready") init();
      }
    );
  }
</script>

Event Listeners

In the init() function you can add as many event listeners for each event that you want to listen and react to. Using the on() function you can register a listener with the first argument of the function being the name of the event and the second argument being the function to call when that event happens.

// Or bookingTool.on(...) if you're using embedded mode.
window.Appointedd.popovers.on("CUSTOMER_DETAILS_STEP", function() {
  console.log("The user is on the customer details step!
});

Some events have additional data that you can also make use of. To do this you simply need to add an argument to your listener function.

// Or bookingTool.on(...) if you're using embedded mode.
window.Appointedd.popovers.on("CUSTOMER_DETAILS_STEP", function(event) {
  // JavaScript object containing data sent by the event.
  console.log(event.data);
});

Available Events

ℹ️ All properties on the additional data for all events are optional unless explicitly stated otherwise. Please ensure that your code can handle validation and/or process properties on the additional data for an event being undefined or null.

`READY`

Happens when the booking tool has successfully loaded and is ready to accept user input.

Additional Data

Property Path	Type	Description
`iFrameId`	string	Unique identifier of the iFrame that is hosting the booking tool.

Example

{
  "data": {
    "iFrameId": "appointedd-widget-iFrame-66e40f99b6e581daf5894740-1"
  },
  "name": "READY"
}

`CLOSE_APPOINTEDD_POPOVER`

Happens when the user closes the booking tool's popover. This will only be able to happen if your booking tool is in popover mode on your page.

Additional Data

Property Path	Type	Description
`iFrameId`	string	Unique identifier of the iFrame that is hosting the booking tool.

Example

{
  "data": {
    "iFrameId": "appointedd-widget-iFrame-66e40f99b6e581daf5894740-1"
  },
  "name": "CLOSE_APPOINTEDD_POPOVER"
}

`USER_ENGAGED`

Happens when the user interacts with the booking tool by clicking on a button or focusing an input field.

Additional Data

Property Path	Type	Description
`iFrameId`	string	Unique identifier of the iFrame that is hosting the booking tool.

Example

{
  "data": {
    "iFrameId": "appointedd-widget-iFrame-66e40f99b6e581daf5894740-1"
  },
  "name": "USER_ENGAGED"
}

`LOCATION_SEARCH`

Happens when the user searches for a location on the location step of the booking flow in the booking tool. This can only happen if you have a location step enabled for your booking tool.

Additional Data

Property Path	Type	Description
`iFrameId`	string	Unique identifier of the iFrame that is hosting the booking tool.

Example

{
  "data": {
    "iFrameId": "appointedd-widget-iFrame-66e40f99b6e581daf5894740-1"
  },
  "name": "LOCATION_SEARCH"
}

`BOOKING_SLOT_RESERVED`

Happens when the user successfully creates a reservation slot by selecting an date and time in the booking flow. This reservation is held for a preset amount of time configured on your account.

Additional Data

Property Path	Type	Description
`iFrameId`	string	Unique identifier of the iFrame that is hosting the booking tool.
`organisationId`	string	Unique identifier for the Appointedd account that the reservation was created in.
`reservationSlotId`	string	Unique identifier for the reservation.
`selectedTimeSlot`	string	Date and time that the reservation is for. Uses the ISO 8601 format.

Example

{
  "data": {
    "iFrameId": "appointedd-widget-iFrame-66e40f99b6e581daf5894740-1",
    "organisationId": "669e2f136812fa18d27b43ca",
    "reservationSlotId": "67530d8d2fd797000da435ee",
    "selectedTimeSlot": "2024-12-06T20:15:00.000Z"
  },
  "name": "BOOKING_SLOT_RESERVED"
}

`BOOKING_CREATED`

Happens when the user successfully creates a booking in the booking tool by completing the booking flow.

Additional Data

Property Path	Type	Description
`iFrameId`	string	Unique identifier of the iFrame that is hosting the booking tool.
`booking`	object	Object containing the details of the customer that made the booking.

booking object

`customer`	object	Object containing the details of the customer that made the booking.
`end_time`	string	Date and time that the booking that was made ends at. Uses the ISO 8601 format.
`id`	string	Unique identifier of the booking that was made.
`organisation_id`	string	Unique identifier of the Appointedd account that the booking was made in.
`organisation_name`	string	Human readable name of the Appointedd account that the booking was made in.
`resource_id`	string	Unique identifier of the Appointedd resource that is assigned to the booking that was made.
`service_id`	string	Unique identifier of the Appointedd service that the booking was made for
`service_name`	string	Human readable name of the Appointedd service that the booking was made for.
`spaces`	numer	Number of spaces that this booking is for.
`timezone`	string	IANA name of the time zone that this booking was made in.

booking.customer object

Property Path	Type	Description
`crmFieldData`	object	Dynamic object containing the custom CRM fields that may have been filled out by the customer when they made the booking. The keys of the objects will be a string ID of the custom CRM field and the associated value will be a string or `null` depending on if the customer filled the CRM field.
`email`	string	Email address of the customer that made the booking.
`firstName`	string	First name of the customer that made the booking.
`lastName`	string	Last name of the customer that made the booking.
`marketingOptIn`	boolean	Indicates if the customer opted-in for marketing communications when making the booking. Only present if you have the marketing opt-in feature enabled on your booking flow.
`phone`	string	Mobile number of the customer that made the booking.

Example

{
  "data": {
    "booking": {
      "customer": {
        "email": "example@appointedd.com",
        "firstName": "John",
        "lastName": "Doe",
        "marketingOptIn": false,
        "phone": "+447874014106",
        "crmFieldData": {
          "Random date": "2023-06-14"
        }
      },
      "end_time": "2024-09-15T09:00:00.000Z",
      "id": "66e418b461ccf157b2549eb3",
      "organisation_id": "66e418b461ccf157b2549eb3",
      "organisation_name": "Example organisation name",
      "service_id": "66e418c5628775f3ba0f7a25",
      "service_name": "Example service name",
      "spaces": 1,
      "start_time": "2024-09-15T08:00:00.000Z",
      "timezone": "Europe/London"
    },
    "iFrameId": "appointedd-widget-iFrame-66e40f99b6e581daf5894740-1"
  },
  "name": "BOOKING_CREATED"
}

`CUSTOMER_DETAILS_STEP`

Happens when the user reaches the customer details step in the booking flow in the booking tool.

Because our booking flow steps are customisable, the additional data emitted with this event depends on what steps have been completed prior to the user arriving at this step.

Additional Data

Property Path	Type	Description
`attendees`	number	Number of attendees on the current booking flow.
`bookingNotes`	string	Additional notes that were added by the customer to the booking for the current booking flow.
`bookingQuestionData`	object	Dynamic object containing the booking questions that were completed by the customer to the booking for the current booking flow.
`bookingQuestionFileNameData`	object	Dynamic object containing the file names of the files that were uploaded by the customer to the booking for the current booking flow.
`bookings`	object[]	Array of objects containing one or more bookings that will be made as part of the current booking flow.
`confirmedBookingIds`	string[]	Array of unique identifiers of any bookings that have been successfully created as part of the current booking flow.
`createdSource`	string	Name or identifier of the source that bookings created by the current booking flow.
`discountCode`	string	Discount code that was used in the booking in the current booking flow for payment.
`duration`	object	Object describing the selected duration of the booking in the current booking flow.
`organisation`	object	Object describing the details of the Appointedd account of the booking in the current booking flow.
`payNow`	boolean	Indicates if the payment is required or selected by the customer if they were given the option of the booking in the current booking flow.
`pricePoints`	object[]	Object describing the details of the price points that were selected by the customer of the booking in the current booking flow.
`recurringBooking`	object	Object describing the current booking if it is a recurring booking in the current booking flow.
`reservedSpaceId`	string	Unique identifier for the reservation of the current booking in the current booking flow.
`resourceGroupId`	string	Unique identifier for the resource group that was selected by the customer for the current booking in the current booking flow.
`resourceIds`	string	Array of unique identifiers of one or more resources that are assigned to the current booking in the current booking flow.
`selectedBookings`	object[]	Array of objects describing the bookings that were selected in the current booking flow as part of the booking flow for a recurring booking.
`selectedTimeSlot`	object	Object describing the time slot that was selected for the booking in the current booking flow.
`service`	object	Object describing the selected service for the booking in the current booking flow.
`sessionId`	string	Unique identifier for the current session of the current booking flow.
`startDate`	Date	Date and time that the booking in the current booking flow starts at. Date and time that the reservation is for. Uses the ISO 8601 format.
`tier`	object	Object describing the tier that was selected for the current booking in the current booking flow if it is a multi-tier booking.
`timezone`	string	IANA name of the time zone of the current booking in the current booking flow.
`totalPaid`	number	Amount paid for the current booking in the booking flow.

booking object

Property Path	Type	Description
`_id`	string	Unique identifier of the booking.
`end`	string	Date and time that the booking ends at. Uses the ISO 8601 format.
`price`	number	Amount that the booking costs.
`remainingSpaces`	number	Remaining number of spaces available to book on the booking.
`start`	string	Date and time that the booking starts at. Uses the ISO 8601 format.
`recurrence`	object	Object that describes how the booking recurs if it is a recurring booking.

duration, service.durations object

Property Path	Type	Description
`default`	boolean	Indicates if this duration is the default duration on the service.
`minutes`	number	Number of minutes that this duration spans.
`oldPrice`	number	Amount that this duration costs before an offer is applied to it.
`POA`	boolean	Indicates if the payment for this duration is taken during the booking flow or expected to be taken when the customer arrives for their booking.
`price`	number	Amount that this duration costs.

organisation object

Property Path	Type	Description
`_id`	string	Unique identifier of this Appointedd account.
`name`	string	Human readable name of this Appointedd account.
`slug`	string	URL safe, partially human readable, unique identifier of this Appointedd account. Used to refer to the Appointedd's account microsite.

resource object

Property Path	Type	Description
`_id`	string	Unique identifier of this resource.
`description`	string	Human readable description of this resource.
`name`	string	Human readable name of this resource.
`profilePhotoUrl`	string	URL to the image of this resource.

service object

Property Path	Type	Description
`_id`	string	Unique identifier of this service.
`availabilityDisplayMode`	string	Indicates how availability for this service should be displayed. Currently supports `CALENDAR` for a calendar view and `LIST` for a list view.
`bookingDepositAmount`	number	Amount required as a deposit when making bookings of this service.
`bookingPaymentOption`	string	Indicates the type of payment required when making bookings for this service, if any. Currently supports `FULL` for a full payment of the price of the booking, `DEPOSIT` for a preset partial amount of the price of the booking, and `NONE` for no payment during the booking flow.
`bookingPaymentOptional`	boolean	Indicates if the payment can be skipped by the customer during the booking flow for bookings of this service.
`category`	object	Object that describes the category that this service belongs to.
`category._id`	string	Unique identifier of this service's category.
`category.name`	string	Human readable name of this service's category.
`description`	string	Human readable description of this service.
`image`	string	URL for the image used when displaying this service.
`isDiscountCodeAvailable`	boolean	Indicates if a discount code is available for this service.
`name`	string	Human readable name of this service.
`numberOfResources`	number	Number of resources that are assigned to this service.
`occupancy`	number	Maximum number of spaces that are available to be booked on bookings for this service.
`resourceAllocationType`	string	Indicates how resources assigned to the service are allocated on this service's bookings Currently supports `ANY` which will select a resource assigned to the service, `ALL` which will select all resources assigned to the service, and `GROUP` which will select all resources assigned to a resource group assigned to the service.
`tiers`	object[]	Array of objects that describe the available tiers that can be selected for this service.
`durations`	object[]	Array of objects that describe the available durations that can be selected for this service.

Example

{
  "data": {
    "attendees": 1,
    "createdSource": "bookingapp",
    "iFrameId": "appointedd-widget-iFrame-669e3291117f84f6b1f64938-1",
    "reservedSpaceId": "67530f4321c143000d079da2",
    "resourceIds": [
      "669e2f136812fa18d27b43d1"
    ],
    "sessionId": "6860252",
    "startDate": "2024-12-06T19:30:00.000Z",
    "timezone": "Europe/London",
    "duration": {
      "default": true,
      "minutes": 30,
      "oldPrice": 0,
      "price": 0
    },
    "organisation": {
      "_id": "669e2f136812fa18d27b43ca",
      "name": "Booking Tools SDK - Production Demo",
      "slug": "booking-tools-sdk---production-demo"
    },
    "service": {
      "_id": "669e2f136812fa18d27b43cf",
      "availabilityDisplayMode": "CALENDAR",
      "bookingDepositAmount": "5",
      "bookingPaymentOption": "FULL",
      "bookingVisibilityType": "BOOKABLE",
      "category": {
        "_id": "669e2f136812fa18d27b43cd",
        "name": "Normal",
        "order": null
      },
      "description": null,
      "image": null,
      "isDiscountCodeAvailable": false,
      "name": "Consultation",
      "numberOfResources": 1,
      "occupancy": null,
      "resourceAllocationType": "ANY",
      "tiers": [],
      "durations": [
        {
          "default": true,
          "minutes": 30,
          "oldPrice": 0,
          "POA": false,
          "price": 0
        }
      ],
      "parts": []
    }
  },
  "name": "CUSTOMER_DETAILS_STEP"
}