Only show these results:

Group availability and booking best practices

📝 This page discusses both Nylas v2.x and v3. For more information about the newest version, see the Nylas v3 documentation.

The simplest form of calendar event is with one or two participants. But what if you need to schedule an event with more complex needs? The hardest part about manually scheduling a meeting with more than a few people is always finding the a time slot where everyone is available. You look from one person's calendar to the next, looking for a time when the right people are available.

With Nylas, you can check calendar-busy information for multiple people, check availability among any number of calendars, and then pass the information you get from these queries to create an event directly, or present the person booking the meeting with several options.

💡 Nylas answers availability requests with available "time slots". These are periods of time that meet your event needs, given additional constraints you set in the request. Time slots are not set periods of time.

Limited-attendance events in v3

Group meetings are renamed "limited-attendance events" in Nylas v3. Unlike v2, they no longer use the Availability endpoint. Instead, event capacity is tracked on the Event object itself. See Limited-attendance events for more information

Collective meetings

In a collective meeting, an organizer hosts an event with a list of participants. You might use this type of meeting when hosting a conference call where all participants are required attendees.

🔍 In Nylas v3, collective meetings are available on all plans. In v2.x, they're in private preview and are available only to a limited audience, on request.

To book a collective meeting, you first make an Availability request (API v3 and API v2), and show the available time slots that meet your criteria to the potential attendee. The attendee selects one of those time slots when they are also available and books the meeting, which creates the event on all participants' calendars.

In v2 there are two types of these meetings: the collective meetings which schedule everyone in the list of participants, and round robin meetings, where the system chooses a participant to assign to the meeting from a list. There are two methods for assigning the participant for a round robin meeting, which are discussed below.

To create a collective or group meeting that includes all participants...

  • In v3, set the availability_method to collective.
  • In v2.x, set the round_robin parameter to null.

Round-robin meetings

In a round-robin meeting, an attendee books 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 book a round-robin meeting, you first make an Availability request (API v3 and API v2), and offer the available time slots that meet your criteria to the potential attendee. The attendee selects a time slot when they are also available and books the meeting, which creates the event for the attendee, and on the selected participant's calendar.

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 API v3, you mark the events that you want to consider with a specific string in their metadata, and in v2.x, you pass an array of email addresses in the event's round_robin_order object.

⚠️ In v2, Nylas uses the time the round-robin event was created when ordering these lists, not the time that the event is scheduled for. In v3, Nylas uses the date and time of the actual scheduled event.

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.

Enabling round-robin

In v3, you specify the round-robin method in the availability_method parameter in the availability_rules. In v2.x, you specify the round-robin method in the round_robin parameter in the body of the Availability request.

Round-robin max fairness groups

In v3, Nylas uses the key5 metadata key to identify events that count toward the max-fairness calculation for each potential participant. For example, you might add "metadata": ["key5": "client-onboarding"] to the events you book this way. When an attendee goes to book additional events, you pass the key5 value of client-onboarding as theround_robin_group_id in the availability request, and Nylas looks at when each participant in the round-robin group was booked for events with that metadata.

To use max-fairness in v2.x, you must pass in an array of emails in round_robin_order when you Create Events. The max-fairness calculation uses this list to assess who was recently booked for this type of meeting. For max-availability in v2.x, Nylas uses the list of emails in the free_busy, calendars, and emails fields.