Skip to main content

Embeddable Widget API

Embeddable Widget API: add JavaScript callbacks to react to widget events like appointment bookings and page views. Trigger pixels, push GTM events, redirect to thank-you pages, or update host-page UI. For server-side actions, use Webhooks.

Felix Livni avatar
Written by Felix Livni
Updated over a week ago

The embeddable widget exposes a small JavaScript surface area so the hosting page can react to what happens inside the widget.

Common use cases:

  • Fire a tracking pixel (or push an event to GTM / dataLayer)

  • Include client context in tracking (e.g., email)

  • Redirect to a custom thank-you page after booking

  • Show/hide or modify parts of the hosting page as the widget navigates

Prerequisites

Requires JavaScript knowledge (you’ll be writing code on the hosting site).

Server-side actions

If you need a server-side action (e.g., call a Zapier endpoint, write to your database), use our Webhooks API instead. The widget callbacks run in the browser.

Events

The widget calls your callbacks (if defined) when certain events occur. You attach handlers by assigning functions on schedulistaWidget.

  • schedulistaWidget.onScheduleAppointment =
    ​ function(appointmentData) { ... }

  • schedulistaWidget.onPageView = function(params) { ... }

Booking event: onScheduleAppointment

Fired every time a client books an appointment via the widget.

schedulistaWidget.onScheduleAppointment = function(appointmentData) {
  // your code here
};

appointmentData payload

{
  id: "abc123",
  time: "2026-01-09T15:30:00-08:00",
  end_time: "2026-01-09T16:00:00-08:00",
  duration: 30,
  service: {
    name: "Initial Consultation"
  },
  client: {
    first_name: "Ada",
    last_name: "Lovelace",
    email: "ada@example.com",
    phone: "+12065551234"
  },
  provider: { /* provider payload */ },
  custom_fields: { /* custom fields */ }
}

Example: send email address to GTM (dataLayer)

Important: Avoid pushing email here if any Google Analytics tags might read it.

window.dataLayer = window.dataLayer || [];

schedulistaWidget.onScheduleAppointment = function(appointmentData) {
  window.dataLayer.push({
    event: "schedulista_appointment_scheduled",
    appointment_id: appointmentData.id,
    appointment_time: appointmentData.time,
    service_name: appointmentData.service && appointmentData.service.name,
    client_email: appointmentData.client && appointmentData.client.email
  });
};

Example: redirect to a custom thank-you page

schedulistaWidget.onScheduleAppointment = function(appointmentData) {
  window.location.href =
    "/thank-you?appointment_id=" + encodeURIComponent(appointmentData.id);
};

Navigation event: onPageView

Fired when the widget navigates between screens.

schedulistaWidget.onPageView = function(params) {
  // your code here
};

params payload

  • page (string): the current widget page identifier (e.g. "choose-service")

Example: show a host-page header only on specific widget pages

schedulistaWidget.onPageView = function(params) {
  const showHeader =
    params.page === "choose-service" || params.page === "limited-offer";

  $(".header").toggle(showHeader);
};

Implementation notes

  • Keep handlers fast; avoid long synchronous work that could degrade UX.

  • If you’re calling third-party scripts, consider wrapping your handler body in try/catch so a vendor error doesn’t break the rest of your page.

Did this answer your question?