Notetaker configurations

A Notetaker configuration is a saved set of notetaker_settings defaults (display name, recording, summary, action items, retention) plus two policies, deduplication and dispatch, that a bot uses when it joins a meeting. You save the defaults once, and Nylas reads them every time it schedules a Notetaker, so you don’t send the same fields on every request. When you update a configuration later, scheduled Notetakers that haven’t joined yet pick up the new values automatically.

Configurations are optional. You can pass notetaker_settings inline on every request instead; see Using Nylas Notetaker.

You can save defaults at several levels, from broadest to most specific. Each section below shows one example of when you’d use that level.

Set defaults across your application

Example: you want every recording in your app to keep media for 7 days instead of the default of 14.

Make a POST /v3/notetakers/configs request with no workspace_id. Every Notetaker in your application inherits these defaults unless something more specific overrides them.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/notetakers/configs' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "Company defaults",
    "notetaker_settings": {
      "name": "Acme Notetaker",
      "recording_type": "audio_video",
      "transcription": true,
      "summary": true
    },
    "deduplication_policy": "active"
  }'

You can have at most one application-level configuration per application. A second POST returns 409 Conflict.

Set defaults for one workspace

Example: one of your customers wants deduplication on and a shorter retention window than the rest of your customers.

A workspace is a grouping of grants (authenticated user accounts). Use one when one customer or team should behave differently than the rest of your application.

Create a workspace with POST /v3/workspaces:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/workspaces' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Acme Sales",
    "domain": "acme.com",
    "auto_group": true
  }'

When auto_group is true, new grants whose email domain matches the workspace’s domain are added automatically. You can also assign grants manually with POST /v3/workspaces/<WORKSPACE_ID>/manual-assign.

Then create a configuration for that workspace by passing workspace_id:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/notetakers/configs' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "workspace_id": "<WORKSPACE_ID>",
    "display_name": "Acme Sales defaults",
    "notetaker_settings": {
      "summary": true,
      "retention_time": 7776000
    },
    "deduplication_policy": "active"
  }'

You can have at most one configuration per workspace.

Set defaults for one calendar

Example: a customer wants their Notetakers to use a custom display name on every meeting from one of their calendars.

You don’t make a separate POST /v3/notetakers/configs call for this. Instead, when you set up calendar sync, include notetaker_settings on the same request. Nylas creates a calendar configuration from those settings. Every Notetaker that joins a meeting on that calendar uses it. To get the assigned config_id, list configurations with GET /v3/notetakers/configs and look for the one whose scope is calendar.

The calendar configuration shows up in GET /v3/notetakers/configs alongside the ones you create yourself, so you can update it with PATCH or remove it with DELETE like any other. See Notetaker calendar sync for the full setup.

Set defaults for one event

Example: a customer wants audio only ("recording_type": "audio") on one specific event.

Same idea, one level deeper. When you set up event sync and include notetaker_settings, Nylas creates an event configuration. Only the Notetaker for that one event uses it. As with the calendar case, list configurations to find its config_id; look for the one whose scope is event.

Pause dispatch with a configuration

Application, workspace, and grant configurations can also carry a dispatch policy. Set dispatch_disabled_until to an RFC 3339 timestamp and Nylas stops sending Notetakers to meetings for that scope until the timestamp passes, without touching calendar rules or scheduled Notetakers. Grant-scope configurations exist only for this purpose: they hold dispatch_disabled_until for one user and never contribute settings. See Pause Notetaker dispatch for the full behavior.

How settings combine

When a Notetaker bot is about to join a meeting, Nylas reads its settings from up to six places, from the most specific to the most general:

Per-request settings (one Notetaker, or one event sync)
  └─ Event configuration (one event, or one recurring series)
       └─ Calendar configuration (one calendar)
            └─ Workspace configuration (one customer or team)
                 └─ Application configuration (your whole app)
                      └─ Platform defaults

The most specific level wins for each field. Anything you don’t set there falls through to the level below. So if your application configuration sets recording_type and a workspace configuration turns on summaries, Notetakers in that workspace get both.

You set the application and workspace configurations yourself. Nylas creates the calendar and event configurations for you whenever you pass notetaker_settings on a calendar sync or event sync request. Per-request is whatever you pass on the POST /v3/notetakers request itself.

Settings are read when the bot joins the meeting, not when you schedule it. If you change a configuration after scheduling a Notetaker but before its join_time, the bot uses the latest values when it joins. The same is true for deduplication: turning it on retroactively affects already-scheduled Notetakers.

Composite settings are replaced whole

Three fields inside notetaker_settings are objects that Nylas treats as a single value rather than merging field by field: transcription_settings, messages, and video_output. When a more specific layer sets one of them, it replaces the parent’s object entirely. To change one field inside, send the whole object you want to end up with; to inherit the parent’s value unchanged, omit the field. Each of the 3 has its own way to clear an inherited value, described on its page: transcription settings, custom announcements, and custom video output.

Update or delete a configuration

PATCH /v3/notetakers/configs/<CONFIG_ID> merges fields, so sending just one field leaves the rest untouched. Updates are versioned; the version field increments on every change. To see past versions, add ?include=history to a GET /v3/notetakers/configs/<CONFIG_ID>.

DELETE /v3/notetakers/configs/<CONFIG_ID> removes a configuration. Notetakers that were using it fall back to the next level above (your application configuration, or the platform defaults).

To list configurations, use GET /v3/notetakers/configs.

Override on a single request

Example: a customer wants different summary and action items instructions for one meeting.

A configuration sets defaults. To override them on one Notetaker, pass notetaker_settings on your POST /v3/notetakers request. Whatever you pass on the request wins; whatever you don’t comes from the inheritance chain.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "meeting_link": "https://meet.google.com/abc-xyz-123",
    "notetaker_settings": {
      "summary": false
    }
  }'

If you have a configuration you want to use without copying its fields, pass config_id on the request instead of inline notetaker_settings. Send one or the other on a given request; mixing config_id with inline notetaker_settings is unsupported.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "meeting_link": "https://meet.google.com/abc-xyz-123",
    "config_id": "<CONFIG_ID>"
  }'

Related topics

• Notetaker deduplication for deduplication_policy.
• Pause Notetaker dispatch for dispatch_disabled_until and grant configurations.
• Notetaker retention policies for retention_time.
• Notetaker transcription settings for transcription_settings.
• Notetaker custom announcements for messages.
• Notetaker custom video output for video_output.
• Migrate to notetaker_settings for the deprecated name and meeting_settings fields.