Set up round-robin meetings

In a round-robin meeting, a guest can book an event with a participant assigned from a list of potential participants. For example, you might use round-robin booking to spread out client onboarding interviews among members of a team.

To set up round-robin meetings, you need to...

Enable round-robin meetings.
Add participants.
Set default open hours.
(Optional) Set participant open hours.

Round-robin methods

There are two types of round-robin calculation: max-availability and max-fairness. They 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 this type. In Nylas v3, you mark the events that you want to consider with a specific string in the event's key5 metadata field.

Participants who have never been booked for this type of event before appear at the top of the list in alphabetical order. Participants who were booked for this type of round-robin event the longest time ago appear next on the list, and participants who were booked most recently are at the bottom of the list. Nylas then checks the availability of each participant for the time period you are attempting to book, and returns all of their available time slots, and a suggested order to book them in.

If you're using max-fairness, Nylas throws out the bottom 50% of the participant list so that 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 in max-availability.

Enable round-robin meetings

To enable round-robin meetings, use the Scheduler API or the Scheduler Editor Component to specify the round-robin method.

Enable round-robin meetings using the Scheduler API

You can make a Create Configuration request or an Update Configuration request to set availability_method to either max-fairness or max-availability.

"availability": {
  "availability_rules": {
    "availability_method": "max-fairness", // "max-availability"
    ...
  }
}

Enable round-robin meetings using the Scheduler Editor

By default, the Scheduler Editor includes a dropdown list for selecting a scheduling method:

Standard booking (for one-on-one or collective meetings)
Round-robin max fairness
Round-robin max availability

To limit the Scheduler Editor so it can only create round-robin meetings, set availability_method to either max-fairness or max-availability for the selectedConfiguration. If you set the availability_method, the Scheduler Editor doesn't show the scheduling method dropdown list when organizers create a Scheduling Page.

HTML/Vanilla JS
React

<html>
  <body>
    <nylas-scheduler-editor />
      
    <script type="module">
      ...
      schedulerEditor.defaultSchedulerConfigState = {
        selectedConfiguration: {
          availability: {
            availability_rules: {
              availability_method: 'max-fairness' // 'max-availability'
            },
          },
        },
      };
    </script>
  </body>
</html>

<NylasSchedulerEditor
  defaultSchedulerConfigState = {
    selectedConfiguration: {
      requires_session_auth: false,
      availability: {
        availability_rules: {
          availability_method: 'max-fairness' // 'max-availability'
        },
      },
    },
  })
/>

Add participants

You add a set of participants to the configuration that you want to include in the round-robin rotation. You can add participants either using the Scheduler API or using the Scheduler Editor.

Add participants using the Scheduler API

You can make a Create Configuration request or an Update Configuration request to add participants to the participants object.

Nylas sets the participant as an organizer for round-robin bookings they're assigned to. Do not manually specify the organizer.
- You must either remove the is_organizer key/value pair or set is_organizer to false for all participants.
Each participant must have a booking calendar and at least one connected calender.
- You must specify calendar_id under booking for each participant. This specifies the participant's booking calendar.
- You must specify calendar_ids under availability for each participant. This specifies the participant's connected calendars.

"participants": [
  {
    "name": "John Smith",
    "email": "j.smith@example.com",
    "availability": {
      "calendar_ids": [
        "j.smith@example.com"
      ]
    },
    "booking": {
      "calendar_id": "j.smith@example.com"
    }
  },
  {
    "name": "Dorothy Perkins",
    "email": "d.perkins@example.com",
    "availability": {
      "calendar_ids": [
        "d.perkins@example.com",
        "en.usa#holiday@group.v.calendar.example.com"
      ]
    },
    "booking": {
      "calendar_id": "d.perkins@example.com"
    }
  },
  {
    "name": "Jane Doe",
    "email": "j.doe@example.com",
    "availability": {
      "calendar_ids": [
        "j.doe@example.com"
      ]
    },
    "booking": {
      "calendar_id": "j.doe@example.com"
    }
  }
]

Add participants using the Scheduler Editor

To add participants to the Scheduling Page, set the additionalParticipants property.

When you set additionalParticipants in the Scheduler Editor Component, the Scheduler Editor UI shows all participants in a dropdown list on the Participants tab. Organizers can:

Select participants to add to the Scheduling Page.
Select whether to include the organizer in the round-robin rotation.

When an organizer adds participants, they must select each participant's booking calendar and connected calendars on the Availability tab. Nylas sets the participant as an organizer for round-robin bookings they're assigned to.

The following examples add additionalParticipants to the Scheduler Editor Component.

🔍 In round-robin meetings, the Scheduler Editor automatically sets the logged-in user as a participant. You don't need to include organizers in additionalParticipants.

HTML/Vanilla JS
React

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

    <script type="module">
      // ...Scheduler Editor Configuration
      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
  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',
        }
      ]
    }]  
  },
  ...
/>

Set default open hours

Default open hours represent the time available for event bookings. 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's connected calendars by default. You can override it by setting participant open hours.

You can set default open hours either using the Scheduler API or using the Scheduler Editor.

Set default open hours using the Scheduler API

You can make a Create Configuration request or an Update Configuration request to set default_open_hours under availability.availability_rules.

The following example shows a default_open_hours object that sets the open hours to between 9:00a.m. and 5:00p.m. in the Chicago timezone, Monday through Friday.

"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 the Scheduler Editor

By default, the Scheduler Editor Component renders the Default open hours picker on the Availability tab.

In the Scheduler Editor, click Availability from the navigation menu.
Under Default open hours, select the timezone and set available hours.
Click Save changes.

The Scheduler Editor shows the Default open hours section on the Availability tab.

(Optional) Set participant open hours

Participant open hours override the default open hours for a participant. You can set participant open hours for each participant either using the Scheduler API or using the Scheduler Editor.

Set participant open hours using the Scheduler API

You can make a Create Configuration request or an Update Configuration request to set open_hours for each participant's availability.

The following example sets a participant's open_hours to between 10:00 a.m. and 6:00 p.m. Toronto time, on Monday, Tuesday, and Wednesday only. It also excludes August 15th as they are not available on that day.

"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 participant open hours using the Scheduler Editor

In the Scheduler Editor, click Participants from the navigation.
Under Participant open hours, click the toggles for the participants that you want to set availability for to enable them.
Select the time zone and set available hours for each participant.
Click Save changes.

The Scheduler Editor shows the Participant open hours section on the Participants tab.