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.
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
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.
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.