Set up collective meetings
Collective meetings let organizers host events with multiple participants from their organization. Scheduler automatically checks the organizer's and participants' availability, then shows guests time slots when everyone is available.
Add participants to Configuration
First, you need to add participants to the Configuration you'll be using for collective meetings. You can add participants using either the Scheduler API or the Scheduler Editor Component.
Add participants using Scheduler API
Make a Create Configuration or Update Configuration request to add participants to the participants object.
⚠️ For collective meetings, you need to identify one of the participants as the organizer ("is_organizer": true).
curl --request PUT \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
--header 'Accept: application/json, application/gzip' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"participants": [
{
"name": "Katherine Perry",
"email": "k.perry.@example.com",
"is_organizer": true,
"availability": {
"calendar_ids": ["k.perry.@example.com"]
},
"booking": {
"calendar_id": "k.perry.@example.com"
}
},
{
"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"]
},
"booking": {
"calendar_id": "d.perkins@example.com"
}
},
{
"name": "Jane Doe",
"email": "j.doe@example.com",
"is_organizer": false,
"availability": {
"calendar_ids": ["j.doe@example.com"]
}
}
]
}' Add participants using Scheduler Editor Component
🔍 For collective meetings, the Scheduler Editor automatically sets the logged-in user as the organizer. You don't need to include organizers in additionalParticipants.
To add participants to the Scheduling Page, set the additionalParticipants property in the Scheduler Editor Component.
<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',
}
]
}
]},
...
/> When you set additionalParticipants, the Scheduler Editor UI shows all specified participants in a dropdown list in the Participants tab. Organizers can select the participants they want to add to the Scheduling Page, then select their connected calendars from the Availability tab.
Set default open hours
Default open hours represent the times available for collective meetings. 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' connected calendars by default. You can override this by setting open hours for individual participants.
You can set default open hours using either the Scheduler API or the Scheduler Editor.
Set default open hours using Scheduler API
Make a Create Configuration or Update Configuration request to set the default_open_hours.
The following example sets the default open hours to between 9:00a.m. and 5:00p.m. in the Chicago timezone, Monday through Friday.
curl --request PUT \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
--header 'Accept: application/json, application/gzip' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"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 Scheduler Editor
By default, the Scheduler Editor renders the default open hours picker in the Availability tab. To set default open hours, navigate to the Availability tab and, under Default open hours, select the timezone and set the available hours.
(Optional) Set open hours for participants
When you set open hours for individual participants, the settings override the default open hours. You can set open hours for each participant using either the Scheduler API or the Scheduler Editor.
Set open hours for participants using Scheduler API
Make a Create Configuration or Update Configuration request to set the open_hours for each participant's availability.
The following example sets a participant's open_hours to between 10:00a.m. and 6:00p.m. in the Toronto timezone, on Monday, Tuesday, and Wednesday only. It also excludes August 15th, because the participant isn't available that day.
curl --request PUT \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
--header 'Accept: application/json, application/gzip' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"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 open hours for participants using Scheduler Editor
You can modify a participant's open hours in the Scheduler Editor by navigating to the Participants tab and, under Participant open hours, select the individuals that you want to set availability for. Select the time zone and available hours for each participant, then save your changes.
