Version:
Only show these results:
private-preview

Using Nylas Notetaker

⚠️ This feature is a private preview release and should be used with caution. It may contain bugs, and its features and implementation will likely change before it is generally available.

💡 Looking for the Notetaker API references? You can find them here!

Nylas Notetaker is a real-time meeting bot that you can invite to online meetings to record and transcribe your discussions.

How Notetaker works

When you invite Notetaker to a meeting, it joins the session as a user and records your discussion. It then transcribes your meeting and sends status updates to you using webhook notifications.

Notetaker can join meetings in three ways:

Notetaker records the meeting until you either remove it from the session or the meeting ends. Then, it processes the data it recorded. Nylas sends notetaker.media webhook notifications as each processed file becomes available for download.

Notetaker changelogs

Set up Notetaker

To follow along with the samples on this page, you first need to sign up for a Nylas developer account, which gets you a free Nylas application and API key.

For a guided introduction, you can follow the Getting started guide to set up a Nylas account and Sandbox application. When you have those, you can connect an account from a calendar provider (such as Google, Microsoft, or iCloud) and use your API key with the sample API calls on this page to access that account's data.

Set up Notetaker notifications

Nylas can send webhook notifications when Notetaker has an update about a media file. To set this up, make a POST /v3/webhooks request with your webhook_url, and include the trigger types you want to subscribe to. You can subscribe to the following Notetaker webhook triggers:

The following example subscribes to notetaker.media and notetaker.meeting_state notifications.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/webhooks/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data-raw '{
    "trigger_types": ["notetaker.media", "notetaker.meeting_state"],
    "description": "Notifications about Notetaker meeting states and updated files.",
    "webhook_url": "<WEBHOOK_URL>",
    "notification_email_addresses": ["nyla@example.com"]
  }'

Invite Notetaker to a meeting

🚀 Notetaker currently supports Google Meet, Microsoft Teams, and Zoom sessions.

When you're ready, invite Notetaker to a meeting by making a POST /v3/notetakers or POST /v3/grants/<NYLAS_GRANT_ID>/notetakers request with a link to your session. The join_time is an optional parameter. If you leave it blank, Notetaker joins the meeting immediately.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "meeting_link": "<MEETING_URL>",
    "name": "Nylas Notetaker",
    "join_time": 1732657774,
    "meeting_settings": {
      "video_recording": true,
      "audio_recording": true,
      "transcription": true
    }
  }'   
{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "notetaker_id": "<NOTETAKER_ID>"
  }
}

When you invite Notetaker to a meeting, Nylas sends a notetaker.meeting_state webhook notification showing that it's attempting to join.

{
  "specversion": "1.0",
  "type": "notetaker.meeting_state",
  "source": "/nylas/notetaker",
  "id": "<WEBHOOK_ID>",
  "time": 1737500935555,
  "webhook_delivery_attempt": 0,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "object": {
      "id": "<NOTETAKER_ID>",
      "grant_id": "<NYLAS_GRANT_ID>",
      "calendar_id": "<CALENDAR_ID>",
      "event": {
        "ical_uid": "<ICAL_UID>",
        "event_id": "<EVENT_ID>",
        "master_event_id": "<MASTER_EVENT_ID>"
      },
      "object": "notetaker",
      "status": "connecting",
      "meeting_state": "dispatched"
    }
  }
}

Notetaker is always considered a non-signed-in user. If your meeting is limited to organization members only, you need to approve Notetaker when it tries to join. If you don't approve its join request within 10 minutes of the scheduled join time, it times out and sends a notetaker.meeting_state webhook notification with the status set to failed_entry.

Nylas doesn't de-duplicate Notetaker bots. Every POST /v3/notetakers or POST /v3/grants/<NYLAS_GRANT_ID>/notetakers request you make invites a new Notetaker to the specified meeting.

Get a list of scheduled Notetakers

You can make a GET /v3/notetakers or GET /v3/grants/<NYLAS_GRANT_ID>/notetakers request to get a list of scheduled Notetaker bots.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

Cancel a scheduled Notetaker

If you no longer need Notetaker in an upcoming meeting, you can make a DELETE /v3/notetakers/<NOTETAKER_ID>/cancel or DELETE /v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/cancel request to cancel the scheduled Notetaker bot.

curl --request DELETE \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/cancel" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

Remove Notetaker from a meeting

Notetaker continues recording your meeting until you either remove it from the session or end the meeting, then it processes the recorded data. If you want to stop recording your meeting before it ends, you can make a POST /v3/notetakers/<NOTETAKER_ID>/leave or POST /v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/leave request to remove Notetaker from your session.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/leave" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

Nylas sends a notetaker.meeting_state webhook notification when Notetaker is removed from a meeting.

{
  "specversion": "1.0",
  "type": "notetaker.meeting_state",
  "source": "/nylas/notetaker",
  "id": "<WEBHOOK_ID>",
  "time": 1737500935555,
  "webhook_delivery_attempt": 0,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "object": {
      "id": "<NOTETAKER_ID>",
      "grant_id": "<NYLAS_GRANT_ID>",
      "calendar_id": "<CALENDAR_ID>",
      "event": {
        "ical_uid": "<ICAL_UID>",
        "event_id": "<EVENT_ID>",
        "master_event_id": "<MASTER_EVENT_ID>"
      },
      "object": "notetaker",
      "status": "disconnected",
      "meeting_state": "api_request"
    }
  }
}

Download processed files

📝 Notetaker can currently recognize up to 10 speakers per transcription.

If you're subscribed to notetaker.media webhook notifications, Nylas sends a notification when a meeting recording or transcription is processing, available to download, or deleted. You can use the media.recording and media.transcript URLs to download the files when they're available.

{
  "specversion": "1.0",
  "type": "notetaker.media",
  "source": "/nylas/notetaker",
  "id": "<WEBHOOK_ID>",
  "time": 1737500935555,
  "webhook_delivery_attempt": 0,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "object": {
      "id": "<NOTETAKER_ID>",
      "object": "notetaker",
      "status": "available",
      "media": {
        "recording": "<RECORDING_URL>",
        "transcript": "<TRANSCRIPT_URL>"
      }
    }
  }
}

You can also download the processed meeting files by making a GET /v3/notetakers/<NOTETAKER_ID>/media or GET /v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/media request. Nylas responds with a link to the recording and a link to the transcript, if available. The links are valid for up to an hour; after that, you need to make another request to get the updated links.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/media" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'   
{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "recording": {
      "url": "<NOTETAKER_RECORDING_URL>",
      "size": 1024
    },
    "transcript": {
      "url": "<NOTETAKER_TRANSCRIPT_URL>",
      "size": 1024
    }
  }
}

⚠️ Nylas stores Notetaker media files for a maximum of three days. After the three-day storage period, the files are deleted and you can't retrieve them using the Nylas API.

What's next?

Now that you're familiar with Nylas Notetaker, take a look at the calendar sync documentation, webhook notification schemas, and Notetaker API references for more information. 🚀