Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

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.

Top Level Configuration

NameTypeDescription
pageDomainstringReplace the editor page URL. pageDomain does not replace the booking page URL, booking links, or email confirmations.
auth.access_tokenstringAccount access token
localestringde, fr, en, es. Change the language of the Scheduler Editor. Learn more about Localization.
locale_for_guestsstringde, 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.
appearanceobjectSee Appearance
bookingobjectSee Booking
eventobjectSee Event
expire_afterobjectSee Expire After
remindersarraySee Reminders
behaviorobjectSee Behavior
timezonestringTimezone to used for email send the host and for opening hours. Timezone using tz database. For example, America/LosAngeles.
disableViewingPagesboolean

🚧

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.

NameTypeDescription
colorstringColor used in place of the default blue on the booking page.
company_namestringName of the company to display on the page title when the Scheduler is embedded.
logostringURL of a logo to display in booking emails and the top left of the booking page
privacy_policy_redirectstringAn 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_autoschedulebooleanDefault true. Pass false to hide the auto-scheduling feature from the booking page.
show_nylas_brandingbooleanShow Nylas branding.
submit_text Doesn't seem to workstringThe text to display on the submit button of the booking page.
thank_you_redirectstringAn 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_textstringThe text to display after a booking is complete
show_week_viewbooleanDefaults 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.

Booking

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

NameTypeDescription
additional_fieldsarray of objectsSet additional dropdown fields in the booking process. See Additonal Fields
available_days_in_futurenumberNumber of days in the future meetings can be booked.
cancellation_policytextText to display when booking an event
confirmation_emails_to_hostbooleanWhether 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_guestsbooleanIf confirmation emails are sent to the event guests. Default is true.
calendar_invite_to_guestsbooleanIf a calendar invite will be sent to event guest.
min_booking_noticenumberMinium minutes into the future a meeting can be booked.
min_buffernumberMinimum time between events
min_cancellation_noticenumberMinimum meetings before a meeting when it can be canceled.
opening_hoursarray of objectsRestrict times and days events can be scheduled.See Opening Hours for more.
scheduling_methodstringround-robin-maximize-fairness or round-robin-maximize-availability
confirmation_methodstringmanual - 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_allowedbooleanDefault true
confirmation_methodstringautomatic, 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.

NameTypeDescription
durationnumberLength (minutes) of the event.
locationstringLocation of the event
titlestringTitle 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.

NameTypeDescription
dropdown_optionsarray of stringsArray of strings for options when the dropdown type is set.
labelstringThe display name of the field.
namestringThe identifier for this field as represented in the API.
requiredbooleanIf the field is required
typeType of field.text, multi-line-text, email, phone, number, dropdown, checkbox.

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.

NameTypeDescription
account_idstringAccount ID to set opening hours.
daysstringDays of the week to book meetings. M, T, W, R, F.
startintegerStart time in 24 hour time clock
endintegerEnd 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.

NameTypeDescription
delivery_methodstringwebhook, email. How the reminder is delivered
delivery_recipientstringcustomer, owner, both.Who the reminder is delivered to.
email_subjectstringNotification text for email and webhooks.
time_before_eventintegerTime in minutes to send the reminder
webhook_urlstringA 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.

NameTypeDescription
dateintegerUNIX timestamp on when the event invitation expires
usesintegerThe maximum number of booking allowed on a page

Behavior

Change the behavior of the schedule editor.

NameTypeDescription
displayOnlyarrayChange the tabs that display in the schedule editor. 'event-info', 'opening-hours', 'calendars', 'reminders'
disableSlugChangesbooleanPrevent users from editing their page slugs. Set to true disables the page

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",
  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

  },
  // 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
    },
    "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"
        }
      ],
      "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
      }
    ]
  }
});

Updated 6 days ago

Scheduler Configuration Reference


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.