Only show these results:

Scheduler Configuration Reference

Whether you use the Scheduling API to create pages or allow your users to create their own pages using the pre-built UI, you can provide page configuration that controls the presentation of the page and the way events are booked.

The config object has several top-level settings and groups additional settings in nested objects.

Booking Flow Query Parameters

When you send users to a booking page, you can pass in your query parameters, for example, https://schedule.nylas.com/mike?patient_id=Ax1233B.

The parameters are saved in the following places:

  • Follow up emails
  • Edit links
  • Cancel links
  • Thank you page

The query parameters ?email and ?name can be prefilled if your application already knows the guest's identity. Guests will still be asked to confirm the booking and provide any additional fields defined in the scheduling page configuration.

Example

https://schedule.nylas.com/nylas-book-me/book/1615997400?prefilled_readonly=true&name=Albert&email=al@einstein.com&custom_field_1=Hello&custom_field_2=World

You can also send the param:

  • prefilled_readonly=true - Any other form values passed in are uneditable by the user.

Passing ?prefilled_readonly=true to a scheduling page URL makes any other form values passed in the query string uneditable by the user.

The user will see the fields grayed out and cannot edit the values. Both standard and custom fields can't be edited.

You can combine prefilled_readonly with iframing to hide the URL bar and prevent users from modifying the values.

Top Level Configuration

Name Type Description
pageDomain string Replace the editor page URL. pageDomain does not replace the booking page URL, booking links, or email confirmations.
auth.access_token string Account access token
locale string de, fr, en, es. Change the language of the Scheduler Editor. Learn more about Localization.
locale12HourTime boolean Change to either 12 hour or 24 hour clock.
locale_for_guests string de, fr, en, es, zh-cn- The locale that guests are shown during booking, leave blank to use their browser locale and allow them to change it on their own.
appearance object See Appearance
booking object See Booking
event object See Event
expire_after object See Expire After
reminders array See Reminders
behavior object See Behavior
timezone string Timezone to used for email send the host and for opening hours. Timezone using tz database. For example, America/LosAngeles.
disableViewingPages boolean

Page Domain Booking Pages

pageDomain does not replace the Booking page URL. Only the editor pages. Email confirmations and booking links will still have Nylas in the URL.

Calendars IDs

You can pass in calendar IDs and available calenders to have control over which calendars can be booked and your availability.

  • The top-level ID is the account_id.
    • availability accepts an array of calendar_ids. When events are being booked, you must be available on all calendars listed; otherwise, the booking will fail.
    • booking - The calendar ID that new bookings will appear. We recommend making a booking calendar and availability calendar the same to prevent duplicate bookings.
...
calendar_ids: {
b5djvgcuhj6i3x8nm53d0vnjm: { # Account ID
availability: ['2fw6navjgkrniaia152z1vn1f'], # Calender IDs where you are free
booking: '2fw6navjgkrniaia152z1vn1f', # Calendar ID where new bookings are saved.
},
},
...

Appearance

Configuration options that control the appearance of the booking page shown to end-users.

Name Type Description
color string Color used in place of the default blue on the booking page.
company_name string Name of the company to display on the page title when the Scheduler is embedded.
logo string URL of a logo to display in booking emails and the top left of the booking page
privacy_policy_redirect string An optional URL to use when guests click the privacy policy links in the booking flow and in follow-up emails. Replaces the standard Nylas privacy policy.
show_autoschedule boolean Default true. Pass false to hide the auto-scheduling feature from the booking page.
show_nylas_branding boolean Show Nylas branding.
submit_text string The text to display on the submit button of the booking page.
thank_you_redirect string An optional URL to redirect to once the booking is complete. The URL receives the new booking_id, name, and email as query parameters. If none is provided, the modal shows a thank you page.
thank_you_text string The text to display after a booking is complete
show_week_view boolean Defaults to true. Pass false to hide the week view from the booking UI. Week view is always hidden for event durations less than 15 minutes.
thank_you_text_secondary string Override the secondary "You'll receive a confirmation email at email@address.com" on the booking confirmation page. Use this when confirmation_emails_to_guests is turned off, and you want to provide more information.

Booking

Booking options allow you to manage the way time slots and availability are calculated and control the booking experience.

Name Type Description
additional_fields array of objects Set additional dropdown fields in the booking process. See Additional Fields
available_days_in_future number Number of days in the future meetings can be booked.
cancellation_policy text Text to display when booking an event
confirmation_emails_to_host boolean Whether to send default emails to the host of the page when the event is modified (during booking, cancellation, and rescheduling.) If you disable these emails and use confirmation_method:manual, you need to implement confirmation emails yourself. See Confirmation Method for more.
confirmation_emails_to_guests boolean If confirmation emails are sent to the event guests. Default is true.
calendar_invite_to_guests boolean If a calendar invite will be sent to event guest.
min_booking_notice number Minimum minutes into the future a meeting can be booked.
min_buffer number Minimum time between events
min_cancellation_notice number Minimum meetings before a meeting when it can be canceled.
opening_hours array of objects Restrict times and days events can be scheduled. See Opening Hours for more.
scheduling_method string round-robin-maximize-fairness or round-robin-maximize-availability
confirmation_method string manual - Host must confirm bookings via email before they are created. external - Thank you redirect provides a custom booking implementation. You will manage the confirmation method and booking process.
additional_guest_emails_allowed boolean Default true
confirmation_method string automatic, manual external. If set to manual, calendar owners will need to confirm new bookings. If set to external then you will manage the confirmation method and booking process.

Event

Set event defaults.

Name Type Description
duration number Length (minutes) of the event.
location string Location of the event
title string Title of the event

Confirmation Method

If you want to manage the entire booking process yourself and do not want the scheduling pages to captures the guest's email address or name on a booking confirmation screen, set confirmation_method: "external".

Confirmation Method will:

  • Redirect the guest to the thank you page immediately after choosing a slot. This is before the booking form.
  • No booking is created.
  • No emails are sent.
  • You should have a thank you page that implements custom booking logic
  • The page owner can not modify Booking Flow, Reminders, or Custom Fields since the booking is not managed by Nylas.

Additional Fields

Including custom fields in the page configuration adds additional fields to the form guests are asked to fill out when booking a meeting. Fields can be required or optional and may be drop-downs, text fields, etc. The values provided are included in the description of the calendar event and also listed in the emails sent to both parties. If you use the Scheduling Pages API to list upcoming bookings programmatically, this data is available in the additional_values object.

Name Type Description
dropdown_options array of strings Array of strings for options when the dropdown type is set.
label string The display name of the field.
name string The identifier for this field as represented in the API.
required boolean If the field is required
type Type of field. text, multi-line-text, email, phone, number, dropdown, checkbox, date, multi-select list.
  • Date fields use the browser's standard date selector. The date is passed to the thank_you_page and in booking emails in ISO format. For example, 2021-12-31.

Opening Hours

Specifying opening hours allows you to restrict the times when bookings may be made to particular days of the week or times of the day. By default, bookings are allowed M-F from 9 AM to 5 PM in the page timezone. Use the account_id to set opening hours per account.

Name Type Description
account_id string Account ID to set opening hours.
days string Days of the week to book meetings. M, T, W, R, F.
start integer Start time in 24 hour time clock
end integer End time in 24-hour time clock

Account Opening Hours

You can set the opening hours per account by adding the account_id.

Account Opening Hours Request

"booking": {  
"opening_hours": [
{
"account_id": "24k1ycmbksw9uonrjwf7nkuty",
"days": ["M", "T", "W", "R", "F"],
"start": "09:00",
"end": "17:00"
},
{
"account_id": "12345678901234567890",
"days": ["M", "W", "F"],
"start": "09:00",
"end": "17:00"
}
],
...
},

You can also combine account level and page level opening hours in one request.

"booking": {  
"opening_hours": [
{
"days": ["M", "T", "W", "R", "F"],
"start": "09:00",
"end": "17:00"
},
{
"account_id": "24k1ycmbksw9uonrjwf7nkuty",
"days": ["S"],
"start": "09:00",
"end": "17:00"
},
{
"account_id": "nrjwf7nbksw9uok2uty4k1ycm",
"days": ["M"],
"start": "17:00",
"end": "21:00"
}
],
...
},

Reminders

Adding one or more reminders to a scheduling page allows you to trigger webhooks or send standard reminder emails at a specified time before each booking. For more information about Scheduling Page webhooks, see the webhooks guide.

You can send multiple reminders and reminder types.

Name Type Description
delivery_method string webhook, email. How the reminder is delivered
delivery_recipient string customer, owner, both.Who the reminder is delivered to.
email_subject string Notification text for email and webhooks.
time_before_event integer Time in minutes to send the reminder
webhook_url string A URL that the scheduling service will make a POST request to with the booking object at the specified time.

Expiration

Providing an expire_after value is only possible using the API. This allows you to programmatically create scheduling pages that are only valid for a set number of uses, or until a specific date.

Name Type Description
date integer UNIX timestamp on when the event invitation expires
uses integer The maximum number of booking allowed on a page

Behavior

Change the behavior of the schedule editor.

Name Type Description
displayOnly array Change the tabs that display in the schedule editor. 'event-info', 'opening-hours', 'calendars', 'reminders'
disableSlugChanges boolean Prevent users from editing their page slugs. Set to true disables the page
disableEditing array slug - Prevent users for editing their page slugs. available_days_in_future - Disable from Schedule Editor.

Complete JSON Example

Tying it all together, here's an example of every configurable feature and how you might pass it when invoking the scheduler in your application.

nylas.schedule.show({
pageDomain: 'https://schedule.myco.com/pages',
auth: {
accessToken: "XXXXXX"
},
locale: "de",
locale12HourTime: "false",
privacy_policy_redirect: "http://www.nylas.com",
// Customization 1: Colors to match your application
style: {
tintColor: "#FF0000",
backgroundColor: "#111111"
},
// Customization 2: Selectively display specific editor tabs
behavior: {
displayOnly: ['event-info', 'opening-hours', 'calendars'],
disableSlugChanges: true,
disableEditing: ['slug', 'available_days_in_future']

},
// Customization 3: Scheduling page defaults that leverage data in your app
defaults: {
"calendar_ids": {
"ecx89ou2e0yqpss57bdo21o7o": {
"availability": [
"63hm8ot6edcyaz8x43sm1i8il"
],
"booking": "63hm8ot6edcyaz8x43sm1i8il"
}
},
"appearance": {
"color": "#0068D3",
"company_name": "Foundry 376",
"show_nylas_branding": false,
"show_autoschedule": true,
"logo": "https://f376-test-bucket.s3.amazonaws.com/nylas-scheduling/43/generic-logo.jpg",
"submit_text": "",
"show_week_view": false,
"thank_you_text": 'Thank you!',
"thank_you_text_secondary": 'We will be in touch soon.'
},
"booking": {
"min_buffer": 30,
"additional_fields": [
{
"dropdown_options": [
"Broccoli",
"Salmon",
"Mushrooms"
],
"required": true,
"type": "dropdown",
"label": "Favorite Foods",
"name": "favorite_foods"
},
{
"required": false,
"type": "multi-line text",
"label": "Notes",
"name": "notes"
},
{
"type": "date",
"label": "Birthdate",
"name": "birthdate",
"required": true
},
{
"type": "multi-select list",
"label": "Colors",
"name": "colors",
"required": true,
"multi_select_options": ["Yellow", "Blue", "Green"]
},
],
"min_booking_notice": 120,
"confirmation_method": "automatic",
"confirmation_emails_to_host": true,
"confirmation_emails_to_guests": true,
"calendar_invite_to_guests": true,
"opening_hours": [
{
"start": "09:00",
"end": "11:30",
"days": [
"M",
"T",
"W",
"R",
"F"
]
},
{
"start": "1:00",
"end": "17:00",
"days": [
"M",
"T",
"W",
"R",
"F"
]
}
],
"available_days_in_future": 14,
"min_cancellation_notice": 180
},
"event": {
"location": "Sightglass Coffee, San Francisco",
"duration": 45,
"title": "Coffee Meeting"
},
"timezone": "America/Los_Angeles",
"reminders": [
{
"delivery_method": "webhook",
"delivery_recipient": "both",
"webhook_url": "https://test.com/callback",
"time_before_event": 60
}
]
}
});