Scheduler overview

The v3 Nylas Scheduler introduces a robust, flexible, secure scheduling solution that you can build seamlessly into your applications. With the v3 Scheduler API and Scheduler UI Components, you can manage bookings, design complex scheduling flows, customize the UI, and much more.

✨ Check out the Scheduler v3 announcements for the latest releases and changes.

How Scheduler works

The v3 Nylas Scheduler has two parts: the Scheduler Editor and Scheduling Pages.

The Scheduler Editor is where organizers can create and manage their Scheduling Pages. When an organizer creates a Scheduling Page they set the event details, such as the event title, duration, buffer time, and which calendar to use to check availability.

Guests use the Scheduling Page to book a time with the organizer. When a booking is confirmed, Scheduler displays a booking confirmation and sends a confirmation email to all participants.

Organizers can also customize their Scheduling page to include links to reschedule and cancel a booking, include additional fields in the booking form, add their company logo to email notifications, and more.

Scheduler supports one-on-one meetings, collective meetings, and round-robin meetings.

Scheduler roles

There are three types of users in Scheduler: organizers, participants, and guests. Participants and guests are sometimes collectively called "attendees".

Organizer: An organizer creates the event. Only one organizer can exist for a Configuration object. Their account is authenticated and connected to Nylas Scheduler.
Attendees: People who attend the event. Attendees include the following:
- Participant(s): A participant is within the organizer’s team or company. All participants are defined in the Configuration object.
- Guest: A guest is the external user who books the event with participants.
- Additional guest(s): A guest can bring additional guests to the event that they book. Their attendance is optional.

Scheduler UI Components

The Scheduler UI Components are pre-built, composable, extensible web- and React-based components. The Scheduler UI Components interact with the Scheduler API so you can quickly create custom scheduling experiences.

Nylas Scheduler includes the following UI Components:

Scheduler Editor Component: Create and customize the Scheduler Editor. Organizers can use the Scheduler Editor to create and edit Scheduling Pages.
Scheduling Component: Create and customize the Scheduling Page. Guests can use the Scheduling Page to book meetings with organizers.

The Scheduler UI Components include...

Custom event handlers that let you implement specific logic or behavior for end user actions in the Nylas Scheduler.
Composable components that allow you to customize how each sub-component is arranged and rendered in the UI.
Custom UI stylings that support CSS shadow parts (::part()) for a higher level of UI customization.

For more information, see the Scheduler UI Components reference.

Scheduler configurations

A configuration is a collection of event settings and preferences. Nylas Scheduler stores Configuration objects in the Scheduler database and loads them as Scheduling Pages in the Scheduler UI.

Nylas Scheduler v3 introduces short-lived session tokens that components use to authorize API requests. A configuration can be either public or private, depending on whether it uses a session.

A public configuration doesn't require a session ID (requires_session_auth: false). Anyone with the link to the associated Scheduling Page can book an event. By default, configurations are public.
A private configuration requires a valid session ID (requires_session_auth: true) to authenticate requests to the scheduling Availability and Bookings endpoints. When you use a private configuration, you can control who can book from the Scheduling Page.

You can follow these steps to generate session tokens in your application:

A user visits your application and authenticates using your project's auth system.
The user loads a Scheduling Page to book an event.
Before showing the Scheduling Page to the user, the application's frontend makes a request to the application's backend system. The backend system can use any custom logic to process further. For example, the backend system can validate that this user is logged in to your application.
The backend system makes a POST /v3/scheduling/sessions request to authenticate the request. This generates a new short-lived session.
The session token is returned to the application's UI, where it can be passed to the Nylas Scheduling Components. The Scheduling Component uses the session token to complete the booking, or stores it somewhere to make requests to the Nylas Scheduler APIs.
The session token expires after the Time-to-Live (TTL), or when Nylas receives a DELETE /v3/scheduler/sessions request. If the session token expires during a user's session on the Scheduling Page, a new one should be generated.

Implement Scheduler in your project

There are several ways you can implement Scheduler in your project. Nylas recommends you follow these steps to determine the best implementation method for your needs:

Choose your implementation approach.
Choose a hosting option for your Scheduling Pages.
Implement the Scheduler Editor.
Create Scheduling Pages.
Set up Scheduler notifications.

Choose your implementation approach

To implement Scheduler in your application, you can either use the Scheduler UI Components or the Scheduler API.

Scheduler UI Component: You can use the Scheduler UI Components as Web components (HTML/Vanilla JS) or React components.
Scheduler API: You can create a configuration and manage bookings using the Scheduler API. If you choose to only use the Scheduler API, you'll be responsible for building your own UI.

Choose a hosting option for Scheduling Pages

You can choose between:

Nylas-hosted Scheduling Pages: When you create a public configuration with a page URL (slug), Nylas automatically hosts the Scheduling Page under the book.nylas.com subdomain.
Self-hosted Scheduling Page: You manage the hosting of Scheduling Pages within your own infrastructure.

Implement the Scheduler Editor

Organizers can use the Scheduler Editor to create and edit Scheduling Pages. You can implement Scheduler with or without the Scheduler Editor.

If you implement the Scheduler Editor for your Nylas-hosted Scheduling Pages, you're responsible for setting up the Scheduler Editor Component in your application, but Nylas handles the hosting of Scheduling pages.

If you're using the Scheduler Editor, you need to decide on the authentication method for the Scheduler Editor Component.

Standard method: Configures nylasSessionsConfig in your application. Use this method if you don't have any auth system set up. This method requires guests to log in every time the access token is expired.
Existing Hosted auth method: Uses the existing Nylas Hosted auth flow in your application. Guests don't have to sign in multiple times.
Access token method: Uses an access token for guests who have already authenticated within the same origin. Guests don't have to sign in multiple times.

Create Scheduling Pages

You can create public or private Scheduling Pages.

Set up Scheduler notifications

You can subscribe to the Scheduler webhook triggers to be notified when changes are made.