Smart Integration
Smart Scheduler allows you to find availability between multiple users at once. This is helpful for when these users don't have access to one another's calendars. Meetings book on one calendar in a [round robin] rotation when passing multiple calendars. Choose between maximizing fairness or availability when applying the [round robin] approach to a calendar rotation.
In comparison, Instant Integration focuses on users freely creating and managing scheduling pages for their own calendars. To create Scheduling Pages with more than one Nylas <ACCESS_TOKEN>
, book meetings via round robin rotations or manage pages programmatically. If you cannot place the Nylas API token in the client application, then Smart Scheduler integration works best for you.
Smart Integration Setup
With Smart Integration, API requests come from your backend server rather than your front-end client to create Scheduling Pages. This protects the Nylas <ACCESS_TOKEN>
client side. It also allows you to pass multiple access tokens when creating a Scheduling Page and enables round robin booking between accounts.
Once you've created a Scheduling Page, retrieve then pass the edit_token
to the client to bring about the Schedule Editor. From here, users to 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 Create a Scheduling Page Request
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": "[email protected]",
"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 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.
POST Create a Scheduling Page Response
{
"access_token_infos": [
{
"account_email": "[email protected]",
"account_name": "Sample Solutions"
}
],
"app_client_id": "<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": "[email protected]",
"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 your application's user wants to manage their Scheduling Pages, retrieve the edit_token
s of one or more pages from your database and open the management embed from your 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 Include Webhooks
Visit the Nylas API Dashboard and navigate to Webhooks > Create a Webhook. Register the following so that changes to calendars-made events update the corresponding bookings.
- URL:
https://api.schedule.nylas.com/webhook
- Triggers:
event.created
event.updated
event.deleted
Round Robin Modes
- Round Robin - Maximize Fairness: Books events evenly across the provided calendars even without availability in the configured time window for the calendar up next. This maximizes booking fairness between the Organizers' calendars to account for all and follow strict order.
- Round Robin - Maximize Availability: If the Organizer next up in booking isn't available, this mode shows other Organizers' availability to maximize bookings for attendees. Here, meetings may not be evenly distributed between Organizers if one is less available than the others.
Set the scheduling_method
parameter to round-robin-maximize-fairness
or round-robin-maximize-availability
within the booking
object. See the 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"
}
}
What's Next
- View in-depth Python and Node example applications.
- Refer to the Customization guide for the full collection of configurable options to pass to the Schedule Editor.