Using calendar sync with Nylas Notetaker

Calendar sync lets Nylas schedule Notetakers for you. You set rules on a calendar that say which events qualify, the service watches the calendar and creates, reschedules, and cancels Notetakers as events change, and the notetaker_settings you attach become a calendar configuration that every one of those bots uses. This page covers setting up the rules, overriding them for a single event, and changing or removing them later.

How Notetaker calendar sync works

When you sync a calendar with Nylas, you set rules that determine whether a Notetaker should be added to each meeting. For example, you can specify that a Notetaker should attend meetings with three participants or more. It searches for events on the calendar that match your rules and schedules a Notetaker for any that it finds.

Nylas automatically re-checks events when they change, and updates Notetakers as necessary (for example, by rescheduling a Notetaker to an event’s updated time). If you cancel an event that has an automatically created Notetaker, the Notetaker is cancelled too.

You can also add Notetaker to individual events, or remove it from individual occurrences. Nylas stops evaluating an event against the calendar’s rules when you set the notetaker object on it with a Create Event or Update Event request. A Cancel Notetaker request on the event’s bot has the same effect. Changing the rules later doesn’t return the event to rule evaluation. See Update or remove an automatically scheduled Notetaker.

As Nylas maintains your Notetakers, it sends webhook notifications to inform you about any changes.

Notetaker calendar sync loop

Your app

Set rules on the calendar

Send a notetaker object with rules on Create or Update Calendar.

Nylas

Check each upcoming event

Only events with a supported meeting link that haven't ended qualify.

No meeting link

Event skipped

No Notetaker is scheduled.

Nylas

Compare with your rules

The event must match event_selection and any participant_filter.

Doesn't match

No Notetaker

Nylas checks the event again if it changes.

Matches

Nylas

Schedule a Notetaker

Uses the calendar's notetaker_settings. Sends notetaker.created.

You change the event's notetaker or cancel the bot

Calendar rules stop applying

Nylas no longer evaluates this event against the calendar's rules.

Calendar

The event changes

Someone moves, edits, or deletes the meeting.

Nylas

Re-check the event

Reschedules the Notetaker if the time or meeting link changed. Sends notetaker.updated.

No longer matches, loses its link, or is deleted

Notetaker cancelled

Sends notetaker.deleted.

Nylas checks events when you set the rules and again whenever an event changes, then schedules, reschedules, or cancels Notetakers to match. Each step names the webhook notification it sends.

Diagram as text

• Your app: Set rules on the calendar: Send a notetaker object with rules on Create or Update Calendar.
• Nylas: Check each upcoming event: Only events with a supported meeting link that haven't ended qualify.
  • No meeting link → Event skipped: No Notetaker is scheduled.
• Nylas: Compare with your rules: The event must match event_selection and any participant_filter.
  • Doesn't match → No Notetaker: Nylas checks the event again if it changes.
• Nylas: Schedule a Notetaker: Uses the calendar's notetaker_settings. Sends notetaker.created. (Matches)
  • You change the event's notetaker or cancel the bot → Calendar rules stop applying: Nylas no longer evaluates this event against the calendar's rules.
• Calendar: The event changes: Someone moves, edits, or deletes the meeting.
• Nylas: Re-check the event: Reschedules the Notetaker if the time or meeting link changed. Sends notetaker.updated.
  • No longer matches, loses its link, or is deleted → Notetaker cancelled: Sends notetaker.deleted.

Set up Notetaker calendar sync rules

When you make a Create Calendar or Update Calendar request, include the notetaker object to set up calendar sync rules. You can configure two sets of rules to control when Notetakers automatically join events: event selection rules and participant filter rules.

Set up event selection rules

When you set up calendar sync, pass rules.event_selection in your request with one or more of these 5 criteria:

• all: Join all events with video conferencing links.
• external: Join events where the host’s email domain is different from the participants’ (for example, meetings with external clients or partners).
• internal: Join events where all participants share the same email domain (for example, all participants’ email addresses have the @nylas.com domain).
• own_events: Join events where the organizer’s email address matches the email address associated with the grant in use.
• participant_only: Join events where the user is in the participant list, but isn’t the organizer.

When you specify multiple event selection rules, Nylas evaluates the top-level items as OR conditions. For example, "event_selection": ["internal", "own_events"] adds a Notetaker to events where all participants share the same email domain, or events where you’re the organizer.

Combine rules with AND logic

Each item in event_selection can be either a single criterion (a string) or a group of criteria (an array of strings). Nylas evaluates items in a nested array as AND conditions, so every criterion in the group must match. Top-level items are still OR’d together, which lets you mix AND groups with single criteria in the same request.

• OR only (flat array): "event_selection": ["internal", "own_events"] matches events that are internal or owned by the user.
• AND only (one nested group): "event_selection": [["own_events", "external"]] matches events that are owned by the user and have at least one external participant.
• Mixed AND/OR: "event_selection": ["internal", ["own_events", "external"]] matches events that are internal, or events that are both owned by the user and have at least one external participant.

Nylas always evaluates participant filter rules as an additional AND condition on top of the event selection result.

Set up participant filter rules

When you set up calendar sync, you can pass rules.participant_filter in your request with either or both of these fields:

• participants_gte: Join events with at least this many participants.
• participants_lte: Join events with at most this many participants.

When you set both, Nylas evaluates them as AND conditions. For example, "participant_filter": {"participants_gte": 3, "participants_lte": 10} adds a Notetaker to events with 3 to 10 participants, inclusive.

Nylas evaluates participant filter rules alongside any event selection rules. The following Update Calendar request adds Notetakers to events with 3 to 10 participants where either the participants all share an email domain or you’re the organizer, and attaches the settings those bots should use.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {
      "notetaker_settings": {
        "name": "Nylas Notetaker",
        "action_items": true,
        "action_items_settings": {
          "custom_instructions": "Only return the 5 most important action items."
        },
        "leave_after_silence_seconds": 600,
        "recording_type": "audio_video",
        "summary": true,
        "summary_settings": {
          "custom_instructions": "Return this summary in the MEDPIC sales methodology."
        },
        "transcription": true,
        "transcription_settings": {
          "expected_languages": ["en", "es"],
          "fallback_language": "en"
        }
      },
      "rules": {
        "event_selection": ["internal", "own_events"],
        "participant_filter": {
          "participants_gte": 3,
          "participants_lte": 10
        }
      }
    }
  }'

If you don’t specify participant filter rules, Nylas adds a Notetaker to any event matching your event selection rules.

To use AND logic, nest the criteria you want to combine inside their own array. This request records every internal meeting plus any external meeting the user organizes, which would otherwise take two separate syncs or filtering on your side.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {
      "rules": {
        "event_selection": ["internal", ["own_events", "external"]]
      }
    }
  }'

The notetaker_settings you send here is saved as a calendar configuration. Every Notetaker that joins a meeting on this calendar uses those values, and anything you don’t set falls through to your workspace and application defaults.

Looking for name or meeting_settings? Those top-level fields are deprecated in favor of the notetaker_settings object shown above. Existing requests still work, but new features like deduplication are only available through the new shape. See Migrate to notetaker_settings for a side-by-side before/after.

Update calendar sync rules and settings

What you change determines which endpoint to use:

• To change notetaker_settings (the bot’s behavior): use PATCH /v3/notetakers/configs/<CONFIG_ID> on the calendar configuration. PATCH merges fields, so you only send what’s changing. The config_id isn’t returned on the calendar response; find it with GET /v3/notetakers/configs and look for the configuration whose scope is calendar.

curl --request PATCH \
  --url 'https://api.us.nylas.com/v3/notetakers/configs/<CONFIG_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker_settings": {
      "summary": false
    }
  }'

• To change calendar sync rules (event_selection, participant_filter): use the calendar PUT. Rules live on the calendar’s notetaker object, not on the configuration, so the config endpoint can’t reach them. PUT replaces the whole nested notetaker object, so include notetaker_settings alongside rules or the settings are wiped.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {
      "notetaker_settings": {
        "summary": true
      },
      "rules": {
        "event_selection": ["all"],
        "participant_filter": {
          "participants_gte": 2
        }
      }
    }
  }'

Remove Notetaker calendar sync rules

To stop Nylas from scheduling Notetakers for a calendar, make an Update Calendar request with an empty notetaker object. This removes the rules and the calendar configuration together. Notetakers that are already scheduled from earlier matches aren’t cancelled by this request; cancel them individually if you don’t want them to join.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {}
  }'

Set up Notetaker event sync

To add a Notetaker to a single event, make a Create Event or Update Event request that includes the notetaker object. This works whether or not the calendar has sync rules, and it’s the way to give one meeting different settings, such as a different display name or a 6-minute silence threshold instead of the default 5.

When you set a Notetaker on a single event, Nylas doesn’t apply calendar-wide rules to it. The settings you send are saved as an event configuration. They override the calendar configuration for that event; anything you don’t set still comes from your calendar, workspace, and application defaults.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {
      "notetaker_settings": {
        "name": "Finance Meeting Notetaker",
        "action_items": true,
        "action_items_settings": {
          "custom_instructions": "Only return the 5 most important action items."
        },
        "leave_after_silence_seconds": 360,
        "recording_type": "audio_video",
        "summary": true,
        "summary_settings": {
          "custom_instructions": "Return this summary in the MEDPIC sales methodology."
        },
        "transcription": true,
        "transcription_settings": {
          "expected_languages": ["en", "es"],
          "fallback_language": "en"
        }
      }
    }
  }'

Update or remove an automatically scheduled Notetaker

Calendar sync creates ordinary Notetakers, so you can change or cancel any one of them with the usual endpoints. To change its settings or join_time, make an Update Notetaker request. To stop it from recording an event that matches your rules, either make a Cancel Notetaker request for that bot, or make an Update Event request with an empty notetaker object.

curl --request PATCH \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "join_time": 1732657774,
    "notetaker_settings": {
      "name": "Nylas Notetaker",
      "action_items": true,
      "action_items_settings": {
        "custom_instructions": "Only return the 5 most important action items."
      },
      "recording_type": "audio_video",
      "summary": true,
      "summary_settings": {
        "custom_instructions": "Return this summary in the MEDPIC sales methodology."
      },
      "transcription": true,
      "transcription_settings": {
        "expected_languages": ["en", "es"],
        "fallback_language": "en"
      }
    }
  }'

Cancelling a Notetaker or setting notetaker on an event takes that event out of rule evaluation. After either request, Nylas stops evaluating the event against the calendar’s rules, so cancelling a bot doesn’t produce another one for the same meeting. Changing event_selection or participant_filter later doesn’t bring the event back. To schedule a Notetaker for it again, make an Update Event request with the notetaker object. An Update Notetaker request leaves the event in rule evaluation.

Keep in mind

• Calendar sync rules apply to each occurrence of a recurring event independently.
• If you manually update a Notetaker on a single occurrence of a recurring event, Nylas doesn’t modify the other occurrences in the series.
• Calendar sync keeps scheduling Notetakers while dispatch is paused; they join once the pause ends.

Related topics

• Notetaker configurations for how calendar and event configurations fit into the inheritance chain.
• Notetaker deduplication to opt a calendar or event out of one-bot-per-meeting behavior.
• Notetaker transcription settings for the language and keyword hints shown in the examples above.