Smart Integration v2
While Nylas's Instant Integration lets users create and manage their own individual calendars, Nylas's Smart Scheduler lets you distribute meetings evenly among a group of users, and manage scheduler pages programmatically. This is also a good way to find availability from a group of users at the same time, even when the scheduler doesn't have access to all calendars.
If you can't put the Nylas API token in your client application, if you need to book meetings using a round-robin rotation system, or if you need to create scheduling pages with more than one Nylas <ACCESS_TOKEN>, then Smart Scheduler integration is the best solution for you.
When you send the Smart Scheduler multiple calendars, the meetings are booked in a "round robin" rotation to try to distribute them evenly among the calendars. Two scheduling modes are available: you can try to create events evenly among calendars ("maximize fairness"), or try to maximize the number of bookable time slots ("maximize availability").
Smart Integration set up overview
With Smart Integration, API requests to create Scheduling Pages come from your backend server rather than your front-end client, so the Nylas <ACCESS_TOKEN> is never sent from the client.
To set up Smart Integration, start by setting up a Scheduling Page as usual. Next, get and pass the edit_token to the client so the user can open the Schedule Editor. From here, users can edit their own Scheduling Pages in-app without having to expose their <ACCESS_TOKEN>.
Scheduling pages API
See the full API reference for managing your Scheduling Pages.
Step 1 API request
Make an API request to create a Scheduling Page from your server. Pass one or more Nylas API tokens or optionally pass a page name, page slug, and initial configuration.
POST example request: create a scheduling page
curl --location --request POST 'https://api.schedule.nylas.com/manage/pages' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"access_tokens": ["<ACCESS_TOKEN>"],
"config": {
"appearance": {
"color": "#82c0e7",
"company_name": "Sample Solutions",
"show_autoschedule": false,
"show_nylas_branding": false,
"show_timezone_options": false,
"show_week_view": false,
"submit_text": "Book it!",
"thank_you_text": "Thanks!"
},
"booking": {
"additional_fields": [{
"dropdown_options": [
"Monday",
"Tuesday"
],
"label": "Your Custom Label",
"multi_select_options": [
"Ice Cream",
"Spaghetti",
"Chips"
],
"name": "user_defined_what_is_your_favorite_food_",
"order": 1,
"pattern": "string",
"required": false,
"type": "multi-select list"
}],
"additional_guests_hidden": false,
"available_days_in_future": 14,
"calendar_invite_to_guests": false,
"cancellation_policy": "string",
"confirmation_emails_to_guests": false,
"confirmation_emails_to_host": false,
"confirmation_method": "automatic",
"min_booking_notice": 0,
"min_buffer": 0,
"min_cancellation_notice": 0,
"name_field_hidden": false,
"opening_hours": [{
"account_id": "<ACCOUNT_ID>",
"days": [
"M",
"T",
"W",
"R",
"F",
"S",
"U"
],
"end": "17:00",
"start": "09:00"
}],
"scheduling_method": "round-robin-maximize-fairness"
},
"calendar_ids": {
"<ACCOUNT_ID>": {
"availability": [
"<CALENDAR_ID>"
],
"booking": "<CALENDAR_ID>"
}
},
"event": {
"capacity": 10,
"duration": 30,
"location": "Coffee Shop",
"participants": [{
"email": "contact@example.com",
"name": "Sample Solutions"
}],
"title": "30-min Coffee Meeting"
},
"locale": "en",
"reminders": [{
"delivery_method": "email",
"delivery_recipient": "customer",
"email_subject": "Your meeting is coming up!",
"time_before_event": 30
}],
"timezone": "America/Los_Angeles"
},
"name": "Sample Solutions Meeting",
"slug": "sample-solutions-meet-01"
}' Step 2 Save the edit_token
Store the new page's edit_token in your database. Allow users to edit the Scheduling Page's configuration in the pre-built UI by passing the edit_token to your front-end application. This also functions in place of a Nylas API token to authenticate API requests to update or delete the page.
Example response: Create a scheduling page response
{
"access_token_infos": [{
"account_email": "contact@example.com",
"account_name": "Sample Solutions"
}],
"app_client_id": "<NYLAS_CLIENT_ID>",
"app_organization_id": 99999,
"config": {
"appearance": {
"color": "#82c0e7",
"company_name": "Sample Solutions",
"logo": "",
"show_autoschedule": false,
"show_nylas_branding": false,
"show_timezone_options": false,
"show_week_view": false,
"submit_text": "Book it!",
"thank_you_text": "Thanks!"
},
"booking": {
"additional_fields": [{
"dropdown_options": [
"Monday",
"Tuesday"
],
"label": "Your Custom Label",
"multi_select_options": [
"Ice Cream",
"Spaghetti",
"Chips"
],
"name": "user_defined_what_is_your_favorite_food_",
"order": 1.0,
"pattern": "string",
"required": false,
"type": "multi-select list"
}],
"additional_guests_hidden": false,
"available_days_in_future": 14,
"calendar_invite_to_guests": false,
"cancellation_policy": "string",
"confirmation_emails_to_guests": false,
"confirmation_emails_to_host": false,
"confirmation_method": "automatic",
"min_booking_notice": 0,
"min_buffer": 0,
"min_cancellation_notice": 0,
"name_field_hidden": false,
"opening_hours": [{
"account_id": "<ACCOUNT_ID>",
"days": [
"M",
"T",
"W",
"R",
"F",
"S",
"U"
],
"end": "17:00",
"start": "09:00"
}],
"scheduling_method": "round-robin-maximize-fairness"
},
"calendar_ids": {
"<ACCOUNT_ID>": {
"availability": [
"<CALENDAR_ID>"
],
"booking": "<CALENDAR_ID>"
}
},
"event": {
"capacity": 10,
"duration": 30,
"location": "Coffee Shop",
"participants": [{
"email": "contact@example.com",
"name": "Sample Solutions",
"status": "noreply"
}],
"title": "30-min Coffee Meeting"
},
"features": {
"collective_meetings": false
},
"locale": "en",
"reminders": [{
"delivery_method": "email",
"delivery_recipient": "customer",
"email_subject": "Your meeting is coming up!",
"time_before_event": 30
}],
"timezone": "America/Los_Angeles"
},
"created_at": "2022-02-02",
"edit_token": "avAPaS3ZFpxUugIkmi8oVveryW7RIpG0",
"id": 1111111,
"modified_at": "2022-02-02",
"name": "Sample Solutions Meeting",
"slug": "sample-solutions-meet-01"
} Step 3 Allow Users to Edit
When a user wants to manage their Scheduling Pages, your app must retrieve the edit_tokens of one or more pages from the database, then open the management embed from your app's JavaScript code.
var btn = document.getElementById('schedule-editor');
btn.addEventListener('click', function() {
nylas.scheduler.show({
auth: {
pageEditToken: "<SCHEDULING_PAGE_EDIT_TOKEN>",
},
style: {
tintColor: '#32325d',
backgroundColor: 'white',
},
});
}); Step 4 Set up webhooks
Next, register an event.deleted trigger, so that the booked events are updated correctly if changes are made by calendars outside the scheduler.
- Go to the Nylas API Dashboard and navigate to Webhooks > Create a Webhook.
- In the Callback URL field, enter
https://api.schedule.nylas.com/webhook - Find and select the
event.deletedtrigger. - Click Create webhook.
You can also use the Nylas Webhook API to create and manage webhooks.
Round Robin modes
When you send the Smart Scheduler multiple calendars, the meetings are booked in a "round robin" rotation to try to distribute them evenly among the calendars. Two modes are available and are described below, and in the calendar availability documentation.
In both modes the scheduler starts by sorting the list of calendars by when it last booked an event on them, with the most recently booked calendars at the end of the list, and any calendars that it has never booked at the top of the list.
-
Round Robin - Maximize Availability: In this mode, the scheduler shows all time slots where at least one person in the list of calendars is available. This maximizes booking options for attendees, but means that meetings may not be evenly distributed among the group. This is especially true if one person is less available than the others.
-
Round Robin - Maximize Fairness: This mode helps book events evenly across the provided calendars. The scheduler first puts all of the calendars in order based on when they were last booked using this calendar, with the most recently booked at the end of the list and those who have not been booked recently at the top. Users who have never been booked appear at the top of the list in alphabetical order. Then the system removes the bottom half of the list, and generates time slots where someone on the remaining list (those who haven't been booked recently) is available. If none of the "up next" users are available, the scheduler starts over using the whole list to check for availability.
Set the scheduling_method parameter in the booking object to round-robin-maximize-fairness or round-robin-maximize-availability. See the Scheduler API reference for more info.
{
"booking": {
"min_buffer": 30,
"additional_fields": [],
"min_booking_notice": 120,
"confirmation_method": "automatic",
"opening_hours": [{
"start": "09:00",
"end": "11:30",
"days": ["M", "T", "W", "R", "F"]
}],
"available_days_in_future": 14,
"min_cancellation_notice": 180,
"scheduling_method": "round-robin-maximize-fairness"
}
} More resources
- Check out the in-depth Python example and Node.js example scheduler applications in the Nylas Samples Github repo.
- See the Customization guide for the complete collection of options you can pass to the Schedule Editor.