# Migrate to notetaker_settings Source: https://developer.nylas.com/docs/v3/notetaker/migrate-from-legacy-settings/ The top-level `name` and `meeting_settings` fields on Notetaker requests are now deprecated in favor of a single `notetaker_settings` object. This page walks through the swap for every endpoint that accepts those fields. > **Info:** > **You don't have to create a configuration to make this change.** The simplest migration is a like-for-like swap: move what you already pass in `name` and `meeting_settings` into `notetaker_settings` on the same request. Inline settings keep working the same way they always have. The request payload is the only thing that changes. Configurations are useful when you want shared defaults across many Notetakers, but they're opt-in. > **Hint:** > **Webhook payloads still carry `meeting_settings`.** While requests have moved to `notetaker_settings`, the resolved settings on the `notetaker.created`, `notetaker.updated`, `notetaker.meeting_state`, and `notetaker.media` webhook payloads continue to appear inside `meeting_settings` for backwards compatibility. Webhook consumers should keep reading from `meeting_settings`. The deduplication shape on webhooks is `meeting_settings.deduplication_settings` (an object with `scope`, `key`, and `workspace_id`), which is the resolved form of the request-side `deduplication_policy` string. ## What's changing - `name` (top-level) → `notetaker_settings.name` - `meeting_settings.*` → `notetaker_settings.*` (the field names inside are identical, except that `video_recording` and `audio_recording` become `recording_type`) - `meeting_settings` and `name` still work today, but new features (such as `deduplication_policy`) are only available through `notetaker_settings` or `config_id`. - You **cannot** mix legacy fields and new fields in the same request. If both `meeting_settings` (or top-level `name`) and `notetaker_settings` are present, Nylas returns a `400 Bad Request`. ## Field mapping Most field names and types inside `meeting_settings` carry over to `notetaker_settings` unchanged. The one exception is recording: the two booleans collapse into a single `recording_type` enum. | Legacy field | New field | Notes | | --- | --- | --- | | `name` (top-level) | `notetaker_settings.name` | Moves inside the settings object. | | `meeting_settings.video_recording` and `meeting_settings.audio_recording` | `notetaker_settings.recording_type` | Two booleans become one enum. `audio_video` replaces both set to `true`; `audio` replaces `video_recording: false` with `audio_recording: true`. | | `meeting_settings.transcription` | `notetaker_settings.transcription` | | | `meeting_settings.transcription_settings.*` | `notetaker_settings.transcription_settings.*` | Language and keyword hints. See [Transcription settings](/docs/v3/notetaker/transcription-settings/). | | `meeting_settings.summary` | `notetaker_settings.summary` | | | `meeting_settings.summary_settings.custom_instructions` | `notetaker_settings.summary_settings.custom_instructions` | | | `meeting_settings.action_items` | `notetaker_settings.action_items` | | | `meeting_settings.action_items_settings.custom_instructions` | `notetaker_settings.action_items_settings.custom_instructions` | | | `meeting_settings.leave_after_silence_seconds` | `notetaker_settings.leave_after_silence_seconds` | | | `meeting_settings.messages` | `notetaker_settings.messages` | Custom chat announcements. See [Custom announcements](/docs/v3/notetaker/custom-announcements/). | Don't send `recording_type` together with `video_recording` or `audio_recording` in the same `notetaker_settings` object; Nylas returns `400 Bad Request` with the message `recording_type cannot be combined with audio_recording or video_recording`. Four fields exist only on the new shape and have no legacy equivalent: `retention_time` and `video_output` inside `notetaker_settings`, `deduplication_policy` alongside it, and `config_id` on the request. ## Migrate a join request Endpoints: [`POST /v3/grants/{grant_id}/notetakers`](/docs/reference/api/notetaker/invite-notetaker/) and [`POST /v3/notetakers`](/docs/reference/api/standalone-notetaker/invite-standalone-notetaker/). ```bash curl --request POST \ --url 'https://api.us.nylas.com/v3/grants//notetakers' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "meeting_link": "https://meet.google.com/abc-xyz-123", "name": "Acme Notetaker", "meeting_settings": { "video_recording": true, "audio_recording": true, "transcription": true, "summary": true, "summary_settings": { "custom_instructions": "Summarize in bullet points." }, "leave_after_silence_seconds": 600 } }' ``` ```bash curl --request POST \ --url 'https://api.us.nylas.com/v3/grants//notetakers' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "meeting_link": "https://meet.google.com/abc-xyz-123", "notetaker_settings": { "name": "Acme Notetaker", "recording_type": "audio_video", "transcription": true, "summary": true, "summary_settings": { "custom_instructions": "Summarize in bullet points." }, "leave_after_silence_seconds": 600 } }' ``` The same swap applies to [`PATCH /v3/grants/{grant_id}/notetakers/{notetaker_id}`](/docs/reference/api/notetaker/update-notetaker/) when updating a scheduled Notetaker. Don't forget those requests: a `PATCH` that still sends top-level `name` alongside `notetaker_settings` returns the same `400`. ## Migrate a calendar sync request Endpoints: [`POST /v3/grants/{grant_id}/calendars`](/docs/reference/api/calendar/create-calendar/) and [`PUT /v3/grants/{grant_id}/calendars/{calendar_id}`](/docs/reference/api/calendar/put-calendars-id/). The `name` and `meeting_settings` fields live inside the `notetaker` object on calendar requests. Move them into `notetaker_settings` within the same object. ```bash curl --request PUT \ --url 'https://api.us.nylas.com/v3/grants//calendars/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "notetaker": { "name": "Sales Calendar Bot", "meeting_settings": { "video_recording": true, "audio_recording": true, "transcription": true, "summary": true, "summary_settings": { "custom_instructions": "Use the MEDPIC sales methodology." } }, "rules": { "event_selection": ["internal", "own_events"], "participant_filter": { "participants_gte": 3, "participants_lte": 10 } } } }' ``` ```bash curl --request PUT \ --url 'https://api.us.nylas.com/v3/grants//calendars/' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "notetaker": { "notetaker_settings": { "name": "Sales Calendar Bot", "recording_type": "audio_video", "transcription": true, "summary": true, "summary_settings": { "custom_instructions": "Use the MEDPIC sales methodology." } }, "rules": { "event_selection": ["internal", "own_events"], "participant_filter": { "participants_gte": 3, "participants_lte": 10 } } } }' ``` The `rules` object (event selection and participant filters) is unchanged. Only the settings block moves. ## Migrate an event sync request Endpoints: [`POST /v3/grants/{grant_id}/events`](/docs/reference/api/events/create-event/) and [`PUT /v3/grants/{grant_id}/events/{event_id}`](/docs/reference/api/events/put-events-id/). Same pattern as calendar sync: the `notetaker` object holds the settings. ```bash curl --request PUT \ --url 'https://api.us.nylas.com/v3/grants//events/?calendar_id=' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "notetaker": { "name": "Finance Meeting Notetaker", "meeting_settings": { "video_recording": true, "audio_recording": true, "transcription": true, "action_items": true, "action_items_settings": { "custom_instructions": "Only return the 5 most important action items." }, "leave_after_silence_seconds": 360 } } }' ``` ```bash curl --request PUT \ --url 'https://api.us.nylas.com/v3/grants//events/?calendar_id=' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "notetaker": { "notetaker_settings": { "name": "Finance Meeting Notetaker", "recording_type": "audio_video", "transcription": true, "action_items": true, "action_items_settings": { "custom_instructions": "Only return the 5 most important action items." }, "leave_after_silence_seconds": 360 } } }' ``` ## What you get after migrating Moving to `notetaker_settings` unlocks features that the legacy fields don't support: - **`deduplication_policy`**: opt a calendar sync or single event out of deduplication. See [Notetaker deduplication](/docs/v3/notetaker/deduplication/). - **`retention_time`**: keep media for longer or shorter than the 14-day default. See [Notetaker retention policies](/docs/v3/notetaker/retention-policies/). - **`video_output`**: the image the bot shows as its camera feed. See [Notetaker custom video output](/docs/v3/notetaker/custom-video-output/). - **`config_id`**: reference a shared [configuration](/docs/v3/notetaker/configurations/) instead of repeating the same settings on every request. - **Future additions**: new fields added to Notetaker will land on `notetaker_settings`, not on `meeting_settings`.