Group availability and booking in v2
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.
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.
🔍 Collective meetings are in private preview and are available only to a limited audience, on request.
To book a collective meeting you first make an Availability request, then 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 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, 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.
You pass an array of email addresses in the event's round_robin_order object, and uses the time the round-robin event was created when ordering these lists, not the time that the event is scheduled for.
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
You specify the round-robin method in the round_robin parameter in the body of the Availability request.
Round-robin max fairness groups
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.