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

Whitelabeling Guide

There are several important ways you can customize the schedule editor and scheduling page as you integrate them into your application. This guide outlines a maximally customized flow - you can opt to implement all or part of the solution outlined here depending on your white-labeling needs.

Schedule Editor Customization

When showing the scheduling page editor, you can customize:

  1. Your own background and theme colors
  2. Defaults specific to your application, so things like the customer's company logo, timezone, event title, etc. are pre-filled and don't require further customization.

Background and Theme Colors

You can set the tintColor and the backgroundColor of the schedule editor upon initialization. Below you can see these color options are set in the style object.

You can easily create your own darkmode version of the schedule editor just by passing a few colors during configuration.

Whitelisted Editor Tabs

An example of the scheduler editor that was configured to only display the reminders tab.

ā€‹
When opening the schedule editor modal in your client-side application, pass the option config.behavior.displayOnly to limit the tabs that appear in the Schedule Editor. If your app uses config.defaults to pass initial values like opening hours, you may want to do this so your users cannot edit your default configuration. At this time, valid tabs are:
ā€‹

  • reminders
  • event-info
  • calendars
  • opening-hours
  • booking-flow
  • custom-fields
  • page-styles

The order you pass the tab IDs has no effect. Unknown tab IDs are ignored, but you must pass at least one valid value.

btn.addEventListener('click', function() {
  nylas.scheduler.show({
    auth: {
      pageEditToken: 'test-edit-token',
    },
    behavior: {
      displayOnly: ['event-info', 'opening-hours', 'calendars'],
    },
    defaults: {
      event: {
        title: 'Introductions',
        duration: 45,
      },
      reminders: [
        {
          delivery_method: 'webhook',
          delivery_recipient: 'both',
          time_before_event: 60,
          webhook_url: 'https://test.com/callback',
        },
      ],
    },
  });
});

Defaults

In the example below, when a user opens the schedule editor in your application and creates a scheduling page, the default settings for that page will contain the values like the title, duration, and company name.

nylas.schedule.show({
  auth: {
    accessToken: "XXXXXX"
  },
  // 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'],
  },
  // Customization 3: Scheduling page defaults that leverage data in your app
  defaults: {
    event: {
      title: "30-min Coffee Meeting",
      duration: 30
    },
    appearance: {
      company_name: "BigCompany",
      logo: "https://assets.site.com/logos/big-company.png"
    },
    booking: {
      additional_fields: [
        {
          label: "Existing Customer",
          name: "existing-customer",
          required: true,
          type: "text"
        }
      ]
    }
  }
});

Scheduling Page Customization

There are several key customizations you can make to the scheduling page:

Custom Theme Color

Your users can customize the theme of their own scheduling pages, updating their color and logo to match their own companies design.

When creating a booking page or calling nylas.schedule.show, pass a custom color in the appearance configuration block to change the highlight color used throughout the scheduling UI. Please keep in mind that you cannot change the background color, and using colors like red, white, and black might confuse some visitors.

{
  "appearance": {
    "color": "#990066"
  },
  ...
}

Custom Logo and Company Name

When creating a booking page via the API or calling nylas.schedule.show, pass a custom company_name and/or logo to change the branding that appears in the top left of the booking flow.

{
  "appearance": {
    "company_name": "BigCompany",
    "logo": "https://assets.site.com/logos/big-company.png"
  },
  ...
}

Custom Book It Button

When creating a booking page via the API or calling nylas.schedule.show, pass custom submit_text to change the label of the Submit button in the booking flow. You might change this to read "Request Appointment" or "Schedule Webinar", for example, if you know more about your customer's meetings.

šŸš§

Don't confuse your visitors!

Keep in mind that if you use Manual Confirmation mode, the button should communicate a "Request to Book" rather than a completed booking.

{
  "appearance": {
    "submit_text": "Schedule Webinar"
  },
  ...
}

Custom Thank You Text and Redirect

When creating a booking page via the API or calling nylas.schedule.show, you can provide thank_you_text to customize the message that appears when the user has completed the booking flow. For more control, you can specify a thank_you_redirect URL and have users redirected to your service.

{
  "appearance": {
    "thank_you_redirect": "https://mysite.com/thanks"
  },
  ...
}

šŸ“˜

Thank you redirect passes relevant data in URL

When using a thank you redirect, The URL includes query string parameters identifying the guest and the booking page that was used so you can run business logic or create a customized message once the user is returned to your application.

Upon redirect the following data is included in the URL

Query ParameterDescription
start_timeUnix timestamp (UTC) of start time of the event.
end_timeUnix timestamp (UTC) of end time of the event.
page_slugThe unique page slug where the event was booked.
tzTimezone setting that was on the scheduling page for the visitor.
nameThe name the attendee entered when booking the event.
emailThe email address the attendee entered when booking the event.
locationThe location for the event
edit_hashUnique ID that can be used to cancel or reschedule a meeting.
event_idThe ID of the Nylas Calendar Event that was created for this booking.
additional_valuesAny additional values that were configured on the booking form.

You can construct a link using the edit_hash value and share it with an attendee who booked a meeting, allowing them to cancel or reschedule the meeting. Here's the URL format:

https://schedule.nylas.com/{{page_slug}}/reschedule/{{edit_hash}}
https://schedule.nylas.com/{{page_slug}}/cancel/{{edit_hash}}
https://mysite.com/thanks?start_time=1568141000&end_time=1568142800&page_slug=mike-pfiser-45min&tz=America/Chicago&name=Guest&email=guest%40company.com&location=Event%40Location%40TBD&edit_hash=12aqwe412&additional_values={}

Upcoming Booking Webhooks

When creating a booking page via the API or calling nylas.schedule.show, pass one or more webhooks in the reminders configuration to receive POST requests to your API when bookings are scheduled or when they're a specific number of hours in the future. You can use webhooks to perform business logic in your application, send push notifications, or send custom emails that leverage data in your application.

Note that the Nylas scheduling service automatically sends out an email when a booking is confirmed, cancelled or rescheduled which includes event details and instructions for the recipients.

See the Scheduler webhooks guide for an example webhook configuration and POST body.

{
  ...
  "reminders": [
    {
      "delivery_method": "webhook",
      "time_before_event": 60, // minutes
      "webhook_url": "https://example.com/api/booking-webhook"
    }
  ],
  ...
}

Want even more white labeling and customization options? Feel free to submit your product feedback here.

Localization

Nylas offers the Scheduler in Spanish, French, German, and English. The Scheduler Editor and Scheduler Booking page use the browser's default language. If the language is not supported, it defaults to English.

Editor

The Scheduler Editor will use the browser to try and set the language for the host. You can also pass in locale to the PageConfiguration to set the editor language. If the language is not set or supported, it will default to the browser settings.

Available languages:

  • locale: "de"
  • locale: "fr"
  • locale: "en"
  • locale: "es"

Locale Example

    <script>
      var btn = document.getElementById('show-pages');
      var accessToken = window.location.href.split('token=').pop();
      btn.addEventListener('click', function() {
        if (!accessToken || accessToken === window.location.href) {
          alert('To test opening the modal with a nylas access token, pass ?token=VALUE in the page URL. You can use the value from your .env file.')
          return;
        }
        nylas.scheduler.show({
          locale: "fr", // <<----- If your app is in French and you want the Scheduler Editor to show in French, regardless of the user's browser settings.  
          auth: {
            accessToken: accessToken,
          },
          behavior: {
            displayOnly: ['reminders']
          },
          defaults: {
            event: {
              title: 'Introductions',
              duration: 45,
            },
            reminders: [
              {
                delivery_method: 'webhook',
                delivery_recipient: 'both',
                time_before_event: 60,
                webhook_url: 'https://test.com/callback',
              },
            ],
          },
        });
      });
    </script>

Confirmation Emails

The host's confirmation emails are sent in the host's language. The language is set in the configuration of the browser.

The participant's confirmation emails are sent in the default language (English). The Scheduler does not translate any information entered by the host. For example, if the location is entered in German, the participants will see the location in German.

Booking Pages

Booking pages will default to your user's browser language. They can change the language using a dropdown on the booking page. The event title and location are not translated.

Booking webhooks will also include a recipient_locale in addition to the other recipient information.

        "recipient_email": "[email protected]",
        "recipient_name": "Nylas Swag",
         "recipient_locale": "en",

Localization Troubleshooting

If you are having trouble with setting your language:

  • Check the browser language
  • Create a new scheduler
  • Review the scheduler locale value

Virtual Calendars

Scheduler supports Virtual Calendars

Updated 3 months ago


Whitelabeling Guide


Suggested Edits are limited on API Reference Pages

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