Group availability and booking best practices
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
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 the Limited-attendance events documentation 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.
To book a collective meeting, you first make an Availability request 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.
To create a collective or group meeting that includes all participants, set the availability_method to collective.
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 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 Nylas v3, you mark the events that you want to consider with a specific string in their metadata.
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 Nylas v3, you specify the round-robin method in the availability_method parameter in the availability_rules.
Round-robin max fairness groups
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.