Customize your Scheduler implementation

Now that you have Scheduler set up, you can customize its appearance and behavior.

Change the Scheduling Page name

By default, Nylas displays the organizer’s user name in the top-left corner of the Scheduling Page Calendar view. To change the page name, you can either…

Set the name field when you make a Create Configuration or Update Configuration request.
Navigate to the Page styles tab in the Scheduler Editor and set the Page name.

Set up rescheduling and cancellation pages

You can customize your Booking Confirmation page and email notifications to include options to reschedule or cancel a booking. If the user clicks one of these buttons, they’re directed to the corresponding page where they can update their booking.

First, you need to add the URLs to your Configuration, then create the rescheduling and cancellation pages.

Add rescheduling and cancellation URLs to Configuration

You can add the rescheduling and cancellation URLs to your Configuration by either making a request to the Scheduler API or modifying the Scheduler Editor Component.

Add URLs to Configuration using Scheduler API

To add the URLs to your Configuration, make an Update Configuration request that includes the scheduler.rescheduling_url and scheduler.cancelling_url parameters.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
     "event_booking": {
      "title": "Testing Scheduler"
      "conferencing": {
        "provider": "Zoom Meeting",
        "autocreate": {
          "conf_grant_id": "<NYLAS_GRANT_ID>",
          "conf_settings": {
            "settings": {
              "join_before_host": true,
              "waiting_room": false,
              "mute_upon_entry": false,
              "auto_recording": "none"
            }
          }
        }
      }
    }
    "scheduler": {
      "rescheduling_url": "https://www.example.com/reschdule/:booking_ref",
      "cancellation_url": "https://www.example.com/cancel/:booking_ref"
    }
  }'

{
  "ID": "<SCHEDULER_CONFIGURATION_ID>",
  "participants": [
    {
      "name": "Nyla",
      "email": "nyla@example.com",
      "is_organizer": true,
      "availability": {
        "calendar_ids": ["primary"]
      },
      "booking": {"calendar_id": "primary"}
    }
  ],
  "availability": {"duration_minutes": 30},
  "event_booking": {"title": "Test event"},
  "scheduler": {
    "rescheduling_url": "https://www.example.com/reschduling/:booking_ref",
    "cancellation_url": "https://www.example.com/cancelling/:booking_ref"
  }
}

When a user confirms their booking, Nylas automatically creates a booking reference and includes it in the rescheduling and cancellation URLs, replacing the :booking_ref placeholder.

Add URLs to Configuration using Scheduler Editor Component

To update your Configuration in the Scheduler Editor Component, set the rescheduling_url and cancelling_url parameters.

<html>
  <body>
    <nylas-scheduler-editor />

    <script type="module">
      import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduler-editor/nylas-scheduler-editor.es.js";

      defineCustomElement();

      const schedulerEditor = document.querySelector('nylas-scheduler-editor');

      schedulerEditor.nylasSessionsConfig = {
        clientId: '<NYLAS_CLIENT_ID>',
        redirectUri: `${window.location.origin}/scheduler-editor`,
        domain: 'https://api.us.nylas.com/v3',
        hosted: true,
        accessType: 'offline',
      }

      schedulerEditor.defaultSchedulerConfigState = {
        selectedConfiguration: {
          scheduler: {
            rescheduling_url: `${window.location.origin}/reschedule/:booking_ref`, // The URL of the email notification includes the booking reference.
            cancellation_url: `${window.location.origin}/cancel/:booking_ref`
          },
        },
      };
    </script>
  </body>
</html>

import React from 'react';
import { NylasSchedulerEditor } from "@nylas/react";

function App() {
  return (
    <NylasSchedulerEditor
      nylasSessionsConfig={{
        clientId: "<NYLAS_CLIENT_ID>",
        redirectUri: `${window.location.origin}/scheduler-editor`,
        domain: "https://api.us.nylas.com/v3",
        hosted: true,
        accessType: 'offline',
      }}

      defaultSchedulerConfigState={{
        selectedConfiguration: {
          scheduler: {
            rescheduling_url:`${window.location.origin}/reschedule/:booking_ref`, // The URL of the email notification includes the booking reference.
            cancellation_url:`${window.location.origin}/cancel/:booking_ref`
          }
        }
      }}
    />
  );
}

export default App;

Create rescheduling and cancellation pages

After you set your URLs, you need to create the corresponding pages.

To create a page where a guest can reschedule their existing booking, create a file and add the Scheduling Component. Then, set the rescheduleBookingRef property to the booking reference that you want to update.

<NylasScheduling
  rescheduleBookingRef="<SCHEDULER_BOOKING_REFERENCE>"
  // You also need to set the Scheduler session ID if using private Configuration (`requires_session_auth=true`).
  // sessionId={"<SCHEDULER_SESSION_ID>"}
/>

To create a page where a guest can cancel their existing booking, create a file and add the Scheduling Component. Then, set cancelBookingRef to the booking reference that you want to cancel.

<NylasScheduling
  cancelBookingRef="<SCHEDULER_BOOKING_REFERENCE>"
  // You also need to set the Scheduler session ID if using private Configuration (`requires_session_auth=true`).
  // sessionId={"<SCHEDULER_SESSION_ID>"}
/>

You can find the booking reference in multiple places: in the rescheduling or cancellation page URL, or in the notifications you receive when you subscribe to the Scheduler notification triggers.

Customize title and body text in confirmation email

You can customize the title and body text in your Scheduler confirmation emails by either making an API request or editing them in the Scheduler Editor.

Customize title and body text using Scheduler API

To update the title and body text, make a Create Configuration or Update Configuration request and specify email_template.booking_confirmed.title and booking_confirmed.body.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "scheduler": {
      "email_template": {
        "booking_confirmed": {
          "title": "Upcoming event with Nylas"
          "body": "Hello, this is to confirm your upcoming event with Nylas."
        }
      }
    }
  }'

Customize title and body text using Scheduler Editor

You can add the nylas-confirmation-email component to the Scheduler Editor to let organizers customize the title and body text of their Scheduler confirmation emails.

Organizers can customize the text by navigating to the Communications tab, scrolling to the Email message section, and modifying the Custom email title and Additional info.

Add company logo to confirmation emails

You can add your company’s logo to your Scheduler confirmation emails by specifying the URL where the image is hosted online. The URL needs to be publicly accessible, and should be a maximum of 100px tall and 200px wide.

To add the logo, either use the Scheduler API or add the logo using the Scheduler Editor.

Add company logo using Scheduler API

You can specify the logo URL in email_template.logo when you make a Create Configuration or Update Configuration request.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "scheduler": {
      "email_template": {
        "logo": "https://www.example.com/logo"
      }
    }
  }'

Add company logo using Scheduler Editor

You can add the nylas-confirmation-email component to the Scheduler Editor to let organizers customize their Scheduler confirmation emails.

Organizers can add a logo to their confirmation emails by navigating to the Communications tab and specifying the Company logo URL.

Disable confirmation emails

By default, Nylas sends a confirmation email to all attendees when a booking is created, rescheduled, or cancelled. If you want to disable confirmation emails, set disable_emails to true in your Configuration.

Style UI Components with CSS shadow parts

The Scheduler UI Components support CSS shadow parts so you can more easily customize your UI. CSS shadow parts let you style certain parts of a web component without having to modify its internal structure or styles directly.

For more information on available shadow parts, see the Scheduler UI Components references.

The following example sets the background and foreground colors for a component on the Scheduling Page.

/* Your stylesheet */
nylas-scheduling::part(ndp__date--selected) {
  background-color: #2563EB;
  color: #FFFFFF;
}

Add styling options to Scheduler Editor

You can add styling options to the Scheduler Editor to allow organizers to customize their Scheduling Pages.

You can include the appearance object in your Configuration. The object accepts key/value pairs where you can pass CSS properties, label changes, and other customizations.

When an organizer configures appearance settings in the Scheduler Editor, or when you make a Create Configuration or Update Configuration request that includes appearance, Nylas updates the appearance object with the information returned and emits the configSettingsLoaded event.

A flow diagram showing the process of configuring appearance settings in the Scheduler Editor.

By default, the Scheduler Editor includes the Page styles tab where organizers can modify the following settings:

Page URL: A URL slug for the Scheduling Page.
Page name: The name of the Scheduling Page, displayed in the top-left corner of the Calendar view. If not set, Nylas displays the organizer’s user name.

You can use the nylas-page-styling component to include extra styling options in the Page styles tab. To use this component, you need to pass custom-style-inputs to the Scheduler Editor Component and include the input fields you want to display. The nylas-page-styling component automatically updates its appearance object when input fields are changed.

For a list of input components that the Scheduler Editor Component supports, see the Scheduler UI Components references.

Be sure to set the name of each input field to match the corresponding key in the appearance object (for example, if appearance includes a company_logo_url key, you need to set "name=company_logo_url" in the input component).

Automatically apply appearance settings

You can add the eventOverrides property to the Scheduling Component to listen for the configSettingsLoaded event. When Scheduler detects the event, it automatically update the Scheduling Component with the modified settings.

This example updates the company_logo_url and, if the URL is valid, displays the logo on the Scheduling Page.

<body>
  <img id="logo" src="" />
  <nylas-scheduling />

  <script type="module">
    const nylasScheduling = document.querySelector('nylas-scheduling');
    const img = document.getElementById('logo');

    nylasScheduling.eventOverrides = {
      configSettingsLoaded: async (event, connector) => {
        const { settings } = event.detail;
        const { company_logo_url } = settings.data.appearance;
        img.src = company_logo_url;
      }
    };
  </script>
</body>

const [appearance, setAppearance] = useState({});
<img
  src={appearance.company_logo_url}
  alt={appearance?.company_name ?? "Company Logo"}
/>

<NylasScheduling
  themeConfig={themeConfig}

  eventOverrides={{
    configSettingsLoaded: async (event, connector) => {
        const { settings } = event.detail;

        if (!settings.data.appearance) {
          setAppearance({});
          return;
        }

        setAppearance(settings.data.appearance);
    }
  }}
  ...
/>

Add styling options to hosted Scheduling Pages

White-labeled hosted Scheduler is available for Contract plans only.

Nylas includes the following pre-defined keys for the appearance object that you can use for Nylas-hosted Scheduling Pages:

company_logo_url: The URL for for the company logo displayed on the Scheduling Page. If not set, Scheduler displays the Nylas logo.
color: The primary color of the Scheduling Page.
submit_button_label: The custom text label for the Submit button.
thank_you_message: The custom “thank you” message on the Confirmation page.

The following examples add the company logo URL, primary color, submit button label, and “thank you” message options to the Scheduler Editor.

<script>
  import { defineCustomElement } from "https://cdn.jsdelivr.net/npm/@nylas/web-elements@latest/dist/cdn/nylas-scheduler-editor/nylas-scheduler-editor.es.js";
  defineCustomElement();
</script>

<nylas-scheduler-editor>
  <div slot="custom-page-style-inputs">
    <label>Company logo URL</label>
    <input-image-url name="company_logo_url"></input-image-url>

    <label>Primary color</label>
    <input-color-picker name="color"></input-color-picker>

    <label>Submit button label</label>
    <input-component name="submit_button_label" type="text"></input-component>

    <label>Thank you message</label>
    <text-area-component name="thank_you_message" placeholder="You'll receive an email confirmation soon.">
    </text-area-component>
  </div>
</nylas-scheduler-editor>

<NylasSchedulerEditor>
  <div slot="custom-page-style-inputs">
    <div>
        <label>Company logo URL</label>
        <InputImageUrl name="company_logo_url" />
    </div>

    <div>
        <label>Primary color</label>
        <div className="color-picker-container">
            <InputColorPicker name="color" />
        </div>
    </div>

    <div>
        <label>Submit button label</label>
        <div>
            <InputComponent name="submit_button_label" type="text" />
        </div>
    </div>

    <div>
        <label>Thank you message</label>
        <div>
            <TextareaComponent name="thank_you_message" placeholder="You'll receive an email confirmation soon." maxLength={500} />
        </div>
    </div>
  </div>
</NylasSchedulerEditor>

Add buffer times to meetings

Nylas Scheduler allows you to add buffer times which ensure there’s space before or after a meeting. This avoids back-to-back meetings and gives participants time to prepare and recover.

You can add buffer times to meetings by including the buffer object in your Create a Configuration object request. Specify the number of minutes before and after a meeting using before and after, respectively. The values can be from 0 - 120 minutes and in increments of five minutes.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "requires_session_auth": false,
    "participants": [{
      "name": "Nyla",
      "email": "nyla@example.com",
      "is_organizer": true,
      "availability": {
        "calendar_ids": ["primary"]
      },
      "booking": {
        "calendar_id": "primary"
      }
    }],
    "availability": {
      "duration_minutes": 30
      "availability_rules": {
        "availability_method": "collective",
        "buffer": {
          "after": 15,
          "before": 5
        }
    },
    "event_booking": {
      "title": "Testing Scheduler"
      "conferencing": {
        "provider": "Zoom Meeting",
        "autocreate": {
          "conf_grant_id": "<NYLAS_GRANT_ID>",
          "conf_settings": {
            "settings": {
              "join_before_host": true,
              "waiting_room": false,
              "mute_upon_entry": false,
              "auto_recording": "none"
            }
          }
        }
      }
    }
  }'

Template variables

Scheduler allows you to use template variables in event titles and descriptions. Scheduler pulls information from the booking request to populate the variables, and generates the final title and description at booking time.

Template variables have a format of ${variable_name}.

Core variables

The following table decribes the core variables available for all Scheduler configurations:

Variable	Description	Example Output
`${invitee}`	The name of the primary invitee. If the name of the invitee is not available, Scheduler uses the invitee’s email instead.	Jane Doe
`${invitee_email}`	The email of the primary invitee.	jane@example.com
`${all_invitee_emails}`	The emails of the primary invitee and any additional guests added at booking time	jane@example.com, jane2@example.com
`{duration}`	The length of time of the event.	30

For example, if the event is 30 minutes and the invitee’s name is Jane, an event title of “${duration}-minute meeting with ${invitee}” would appear as “30-minute meeting with Jane” at the time of booking. If the name wasn’t provided, the title would appear as “30-minute meeting with jane@example.com”.

Additional field variables in Scheduler API

If you add the additional_fields object in your Create a Configuration object request, you can use the field labels in the object as variables.

For example, if your API request contains the additional_fields object as shown below, the event description of “${meeting_type} with ${invitee} from ${company_name}” would appear as “Sales Call with Jane Doe from Acme Corp” at the time of booking.

{
  "additional_fields": {
    "company_name": {
      "label": "Acme Corp",
      "type": "text",
      "required": true
    },
    "meeting_type": {
      "label": "Type of Meeting",
      "type": "dropdown",
      "options": ["Sales Call", "Support", "Demo"],
      "required": true
    }
  }
}

Additional field variables in Nylas-hosted Scheduling Pages

Nylas-hosted Scheduling pages automatically generate the field labels that can be used as variables.

The auto-generated field labels are case preserved and have a format of {field_type}_{label_with_hyphens}_{number}. The number generated is the next available number in the sequence.

The following table shows examples of auto-generated labels and the corresponding variables.

Field Type	Default Label	Auto-generated Label	Variable
Text	Short Text Label	`text_Short-Text-Label_1`	`${text_Short-Text-Label_1}`
Email	Additional Email	`email_Additional-email_1`	`${email_Additional-email_1}`
Phone number	Phone Number Label	`phone_number_Phone-Number-Label_1`	`${phone_number_Phone-Number-Label_1}`
Dropdown	Dropdown Label	`dropdown_Dropdown-Label_1`	`${dropdown_Dropdown-Label_1}`

Don’t change field labels after you use them in event titles and descriptions because if you do, the corresponding variable is deleted. Consider using the Scheduler API for concise variable names and check the generated field labels before using them in titles and descriptions.

Best practices for variables

We recommend the following best practices when working with variables in Scheduler:

If you’re using the Scheduler APIs, use descriptive labels such as company_name and phone_number.
If you’re using Nylas-hosted Scheduling Pages, ensure the labels are concise.
Always test the event titles and descriptions with sample data before going live.

Troubleshooting variables

This section describes common issues you might encounter when working with variables in Scheduler.

Variables aren’t populated with field label values

If variables aren’t populated with field label values at booking time, check if the field label matches the variable name and ensure the label is marked as required.

Field label values aren’t rendering correctly

If you’re using Nylas-hosted Scheduling Pages and the field label values aren’t rendering correctly at booking time, verify if the field labels haven’t changed.