The embeddable widget exposes a JavaScript API so the hosting page can react to events inside the widget and control its behavior.

Advanced integration

Requires JavaScript knowledge.

Common use cases:

Fire a tracking pixel or push an event to GTM / dataLayer
Pre-fill client information in the booking form
Redirect to a custom thank-you page after booking
Show, hide, or modify parts of the hosting page as the widget navigates

If you need deep linking within the widget (no JavaScript required), see Widget Deep Links. If you need server-side actions (e.g., call a Zapier endpoint or write to your database), use the Webhooks API instead.

Events

Attach handlers by assigning functions on schedulistaWidget.

onReady

Fired when the widget has finished loading and is ready to accept commands. This is the recommended place to call prefill() and setOptions().

schedulistaWidget.onReady = function() {
  // Widget is ready
};

onScheduleAppointment

Fired when a client books an appointment. The callback receives an appointmentData object:

schedulistaWidget.onScheduleAppointment = function(appointmentData) {
  // appointmentData contains:
  // {
  //   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: { ... },
  //   custom_fields: { ... }
  // }
};

Example: push to GTM dataLayer

Important: Avoid pushing email to the dataLayer 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,
    service_name: appointmentData.service && appointmentData.service.name
  });
};

Example: redirect to a thank-you page

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

onPageView

Fired when the widget navigates between screens. The callback receives a params object with a page property (e.g., "choose-service").

schedulistaWidget.onPageView = function(params) {
  console.log('Widget page:', params.page);
};

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

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

  document.querySelector(".header").style.display =
    showHeader ? "" : "none";
};

Methods

prefill(data)

Pre-fills the booking form with client information. Only empty form fields are filled; values the client has already typed are not overwritten.

schedulistaWidget.prefill({
  email: 'jane@example.com',
  first_name: 'Jane',
  last_name: 'Doe',
  phone: '555-1234'
});

Field	Description
`email`	Client email address
`first_name`	Client first name
`last_name`	Client last name
`phone`	Client phone number

Calling prefill() multiple times merges new values with previously set ones. Best called inside onReady.

setOptions(options)

Controls how parts of the widget are displayed.

schedulistaWidget.setOptions({ hideOfferHeader: true });

Option	Description
`hideOfferHeader`	When `true`, hides the service/offer header in the widget

Calling setOptions() multiple times merges new options with previously set ones. Best called inside onReady.

navigate(path)

Navigates the widget to a specific page. Useful for building your own service selection UI.

schedulistaWidget.navigate('salon?service_id=1073891883');
schedulistaWidget.navigate('salon?service_id=1073891883&provider_id=1073746138');

For details on deep linking (including hash-based navigation without JavaScript), see Widget Deep Links.

Best practices

Keep handlers fast; avoid long synchronous work that could degrade UX.
Wrap third-party script calls in try/catch so a vendor error doesn't break your page.

keywords: widget, API, JavaScript, embed, callback, onScheduleAppointment, onPageView, onReady, prefill, setOptions, navigate, GTM, dataLayer, tracking

Widget Deep Links

Embeddable Widget API