Set up round-robin meetings
Round-robin meetings let guests book an event with a participant chosen from a list of potential participants. For example, you might use round-robin bookings to distribute client onboarding interviews among members of a team.
How round-robin meetings work
Nylas offers two types of round-robin calculation: max-availability and max-fairness. Both start their calculations in the same way. First, Nylas looks at the list of participants and determines when they were last booked for a round-robin event of the same type. Nylas uses the metadata in an event's key5 field to determine its type (for more information, see Metadata).
Participants who have never been booked for this type of event appear at the top of the list, in alphabetical order. Participants who were booked for this type of event most recently appear at the bottom of the list.
Nylas checks the availability of each participant for the specified time period and returns all of their available time slots, along with a recommended order to book the participants in.
If you're using max-fairness, Nylas discards the bottom 50% of the participant list so it evaluates only those who have not been booked recently. If no time slots are available in the specified period using max-fairness, Nylas falls back to using the full list as it does in max-availability.
Enable round-robin meetings
You can enable round-robin meetings in Scheduler using either the Scheduler API or the Scheduler Editor Component.
Enable round-robin meetings using Scheduler API
Make a Create Configuration request, set the availability_method to either max-fairness or max-availability, and include a list of participants.
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"
}
},
{
"name": "John Smith",
"email": "j.smith@example.com",
"availability": {
"calendar_ids": ["j.smith@example.com"]
},
"booking": {
"calendar_id": "j.smith@example.com"
}
}
],
"availability": {
"duration_minutes": 30,
"availability_rules": {
"availability_method": "max-fairness"
}
},
"event_booking": {
"title": "Testing Scheduler"
}
}' You need to set booking.calendar_id and availability.calendar_ids for each participant. This specifies their booking calendar and connected calendars.
Enable round-robin meetings using Scheduler Editor Component
By default, the Scheduler Editor UI displays a dropdown list where organizers can select one of the following scheduling methods:
- Standard booking (for one-on-one or collective meetings).
- Round-robin meeting using max fairness.
- Round-robin meeting using max availability.
To limit the Scheduler Editor to round-robin meetings only, set selectedConfiguration.availability_method to either max-fairness or max-availability and include the additionalParticipants property.
🔍 When you set the availability method, the Scheduler Editor UI doesn't show the scheduling method dropdown. Instead, Scheduler creates meetings using the specified availability method only.
<html>
<body>
<nylas-scheduler-editor />
<script type="module">
...
schedulerEditor.defaultSchedulerConfigState = {
selectedConfiguration: {
availability: {
availability_rules: {
availability_method: 'max-fairness'
},
},
},
};
schedulerEditor.additionalParticipants = [
{
name: 'Dorothy Perkins',
email: 'd.perkins@example.com',
calendars: [
{
id: 'd.perkins@example.com',
name: 'Dorothy Perkins',
},
{
id: 'en.usa#holiday@group.v.calendar.example.com',
name: 'Holidays'
}
],
},
{
name: 'Jane Doe',
email: 'j.doe@example.com',
calendars: [{
id: 'j.doe@example.com',
name: 'Jane Doe',
}],
}
]
</script>
</body>
</html> <NylasSchedulerEditor
defaultSchedulerConfigState = {
selectedConfiguration: {
requires_session_auth: false,
availability: {
availability_rules: {
availability_method: 'max-fairness'
},
},
},
},
additionalParticipants = {[
{
name: 'Dorothy Perkins',
email: 'd.perkins@example.com',
calendars: [
{
id: 'd.perkins@example.com',
name: 'Dorothy Perkins',
},
{
id: 'en.usa#holiday@group.v.calendar.example.com',
name: 'Holidays'
}
]
},
{
name: 'Jane Doe',
email: 'j.doe@example.com',
calendars: [{
id: 'j.doe@example.com',
name: 'Jane Doe',
}]
}
]},
/> When you set additionalParticipants, the Scheduler Editor UI shows the specified participants in a dropdown list on the Participants tab. From there, organizers can...
- Select participants to add to the Scheduling Page.
- Decide whether to include the organizer in the round-robin rotation.
When an organizer adds participants to a round-robin meeting, they must select each participant's booking calendar and connected calendars in the Availability tab. Nylas automatically sets the selected participant as an organizer for round-robin meetings that they're assigned to.
Set default open hours
Default open hours represent the times available for round-robin meetings. Think of this as setting the "working hours" on a calendar, so nobody books a meeting in the middle of the night with your team on the East Coast.
Default open hours apply to all participants' connected calendars by default. You can override this by setting open hours for individual participants.
You can set default open hours using either the Scheduler API or the Scheduler Editor.
Set default open hours using Scheduler API
Make a Create Configuration or Update Configuration request to set the default_open_hours.
The following example sets the default open hours to between 9:00a.m. and 5:00p.m. in the Chicago timezone, Monday through Friday.
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 '{
"availability": {
"availability_rules": {
"default_open_hours": [{
"days": [1, 2, 3, 4, 5],
"timezone": "America/Chicago",
"start": "9:00",
"end": "17:00"
}]
}
}
}' Set default open hours using Scheduler Editor
By default, the Scheduler Editor renders the default open hours picker in the Availability tab. To set default open hours, navigate to the Availability tab and, under Default open hours, select the timezone and set the available hours.
(Optional) Set open hours for participants
When you set open hours for individual participants, the settings override the default open hours. You can set open hours for each participant using either the Scheduler API or the Scheduler Editor.
Set open hours for participants using Scheduler API
Make a Create Configuration or Update Configuration request to set the open_hours for each participant's availability.
The following example sets a participant's open_hours to between 10:00a.m. and 6:00p.m. in the Toronto timezone, on Monday, Tuesday, and Wednesday only. It also excludes August 15th, because the participant isn't available that day.
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 '{
"participants": [
{
"name": "Dorothy Perkins",
"email": "d.perkins@example.com",
"is_organizer": false,
"availability": {
"calendar_ids": ["d.perkins@example.com","en.usa#holiday@group.v.calendar.example.com"],
"open_hours": [{
"days": [1, 2, 3],
"timezone": "America/Toronto",
"start": "10:00",
"end": "18:00",
"exdates": ["2024-08-15"]
}]
},
"booking": {
"calendar_id": "d.perkins@example.com"
}
}
]
}' Set open hours for participants using Scheduler Editor
You can modify a participant's open hours in the Scheduler Editor by navigating to the Participants tab and, under Participant open hours, select the individuals that you want to set availability for. Select the time zone and available hours for each participant, then save your changes.
