Version:
Only show these results:

Scheduler v2 web reference

How you choose to create your Scheduler Editor and Pages will determine which configuration options are available.

  • App - If you want to create pages directly in your app using nylas.scheduler and do not want to use the API, then take a look at our Scheduler Web Reference.
  • API - If you want to create pages using the API, take a look at our API reference.

Top Level Configuration

The config object has several top-level settings. Additional settings are in nested objects.

Name Type Description
pageDomain string Replace the Schedule Editor page URL. pageDomain does not replace the Scheduling Page URL, booking links, or email confirmations.
auth.access_token string Account access token.
locale string de, fr, en, es, sv, zh-cn. Change the language of the Scheduler Editor. Learn more in the Localization section.
locale12HourTime boolean Toggles between 12 hour or 24 hour clock.
locale_for_guests string de, fr, en, es, zh-cn. The locale guests see 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 The timezone used for opening hours and email notifications sent to the host. The timezone must be an IANA time zone database formatted string. For example, America/Chicago.
disableViewingPages boolean Deactivate viewing page.
disable_emails boolean Deactivate all email communication from Scheduler.

Page Domain Booking Pages

pageDomain does not replace the Scheduling Page URL. The configuration only changes Scheduler Pages. Email confirmations and booking links continue to have a Nylas URL.

Calendars IDs

You can pass <CALENDAR_ID> and available calendars to control specific calendars for booking and your availability.

  • <ACCOUNT_ID> is the top-level ID.
    • availability accepts a <CALENDAR_ID> array. When booking events, you must be available on all calendars listed, otherwise the booking is not valid.
    • booking contains <CALENDAR_ID> for new bookings. Prevent duplicate bookings by making the booking calendar and availability calendar the same.
    "calendar_ids": {
      "<ACCOUNT_ID>": {
        "availability": [
          "<CALENDAR_ID>"
        ],
        "booking": "<CALENDAR_ID>"
      }
    },

Appearance

Configuration options here control the appearance of the Scheduling Page for end-users.

Name Type Description
color string Color used in place of the default blue on the Scheduling 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 at the top left of the Scheduling 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 Defaults to true. Pass false to hide the auto-scheduling feature from the Scheduling Page.
show_nylas_branding boolean Show Nylas branding.
show_timezone_options boolean Display timezone on Scheduling Page. Defaults to true.
submit_text string The text to display on the submit button of the Scheduling 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>@<domain>.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 configuration for time slots and availability 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. Allowed values: 1,2,3,4
cancellation_policy text Text to display when booking an event.
confirmation_emails_to_host boolean Host to receive default emails when the event is modified as any booking, cancellation, and rescheduling changes. Deactivating these emails and using confirmation_method:manual requires you to implement your own confirmation emails. See Confirmation Method for more.
confirmation_emails_to_guests boolean Event guests to receive confirmation emails. Default is true.
calendar_invite_to_guests boolean Event guests to receive a calendar invite.
min_booking_notice number Minimum minutes into the future for booking a meeting.
min_buffer number Minimum time between events. Allowed values: 0,15,30,45,60,75,90
min_cancellation_notice number Minimum time before a meeting for being able to cancel. Allowed values: 0-23
opening_hours array of objects Restrict times and days for scheduling events. See Opening Hours for more.
scheduling_method string Sets round-robin-maximize-fairness or round-robin-maximize-availability.
additional_guests_hidden boolean Defaults to true.
confirmation_method string automatic, manual, external. Defaults to automatic. If set to manual, calendar owners need to confirm new bookings via email before they are created. If set to external, you manage the confirmation method and booking process.

Event

Set event defaults.

Name Type Description
duration number Length (minutes) of the event. Allowed values: 15,30,45,60,75,90
location string Location of the event.
title string Title of the event.

Confirmation Method

To manage the entire booking process yourself and deactivate the Scheduling Pages to capture the guest's email address or name on a booking confirmation screen, set the confirmation_method: "external" configuration. This option includes other interactions.

  • Redirects the guest to the thank you page immediately after choosing a slot. This is before the booking form.
  • No booking is created and no emails are sent.
  • The page owner can't modify Booking Flow, Reminders, or Custom Fields as the booking is not managed by Nylas.

Best Practices

Include a custom thank you page to implement custom booking logic.

Additional Fields

Add additonal fields to the form for your guests by including custom fields in the page configuration. When attendees are booking a meeting, fields can be required or optional as well as other options.

The description of the calendar event contains the values and are also included in the emails for both organizer and attendee.

The data is available in the additional_values object if you're using the Scheduling Pages API to list upcoming bookings.

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.
multi_select_options array string Array of strings for options when type is multi-select list.
name string The identifier for this field as represented in the API.
order number Value for order of field to appear on booking form. The name and email fields set to 0. Negative values are valid.
pattern string Regex pattern to validate user input for text, phone, and number fields. Typically begins with ^ and end with $ for entire field value.
required boolean If the field is required.
type Type of field. Valid inputs of text, multi-line text, email, phone, number, dropdown, checkbox, date, multi-select list.

Keep in Mind

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, as 2021-12-31.

Opening Hours

Specifying opening hours allows you to restrict the available times for bookings. By default, bookings are allowed Monday through Friday 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, S, U.
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": "<ACCOUNT_ID>",  
      "days": ["M", "T", "W", "R", "F"],  
      "start": "09:00",  
      "end": "17:00"  
    },  
   {  
      "account_id": "<ACCOUNT_ID>",  
      "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": "<ACCOUNT_ID>",  
      "days": ["S"],  
      "start": "09:00",  
      "end": "17:00"  
    },  
    {  
      "account_id": "<ACCOUNT_ID>",  
      "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.
time_before_event integer Time in minutes to send the reminder.
webhook_url string A URL for making a POST request at the specified time with the booking object and scheduling service.

Expiration

Providing an expire_after value is only possible using the API. This allows you to programmatically create temporary Scheduling Pages. For example, a page may only be 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

This comprehensive example of every configurable feature and demonstrates the robust ways for implementing Scheduler in your application.

nylas.schedule.show({
pageDomain: 'https://example.com/pages',
  auth: {
    accessToken: "<ACCESS_TOKEN>"
  },
   locale: "de",
   locale12HourTime: "false",
  // 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": {
      "<ACCOUNT_ID>": {
        "availability": [
          "<CALENDAR_ID>"
        ],
        "booking": "<CALENDAR_ID>"
      }
    },
    "appearance": {
      "color": "#0068D3",
      "company_name": "Foundry 376",
      "show_nylas_branding": false,
      "show_autoschedule": true,
      "logo": "https://s3.example.com/nylas-scheduling/43/generic-logo.jpg",
      "submit_text": "",
      "show_timezone_options": true,
      "show_week_view": false,
      "thank_you_text": 'Thank you!',
      "thank_you_text_secondary": 'We will be in touch soon.'
      "privacy_policy_redirect": "https://www.nylas.com",
    },
    "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://example.com/callback",
        "time_before_event": 60
      }
    ]
  }
});