Skip to content
Docs
or

Using Nylas Notetaker

Nylas Notetaker API is available for Contract plans only.

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

How Notetaker works

Section titled “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 sends a message to attendees using the meeting provider’s messaging function a few minutes after joining the call. This message informs users that Notetaker is recording and transcribing the meeting, and that it’s the meeting host’s responsibility to collect consent.

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.

Set up Notetaker

Section titled “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

Section titled “Set up Notetaker notifications”

Nylas can send webhook notifications about Notetakers, like when they join calls and when recordings are available. You can set this up through the Nylas Dashboard or by making a POST /v3/webhooks request with your webhook_url and the trigger types you want to subscribe to. You can subscribe to the following Notetaker webhook triggers:

Invite Notetaker to a meeting

Section titled “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.

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",
      "state": "connecting",
      "meeting_state": "dispatched"
    }
  }
}

Notetaker is always considered a non-signed-in user on the meeting platform. 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.

Enable summaries and action items

Section titled “Enable summaries and action items”

When you invite a Notetaker bot to a meeting or update a scheduled Notetaker, you can also enable summaries and action items for the meeting by setting summary and action_items to true. Nylas automatically generates a short summary of the meeting and a list of action items based on your conversation.

If you want to pass custom instructions for either the summary or list of action items, you can specify summary_settings.custom_instructions and action_items_settings.custom_instructions in your request. Nylas’ AI model takes these instructions into consideration while generating the information.

Nylas returns URLs for files that contain the summary and action items. For information on downloading those files, see Handling Notetaker media files.

Get a list of scheduled Notetakers

Section titled “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

Section titled “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

Section titled “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"
    }
  }
}

Troubleshoot Notetaker using history events

Section titled “Troubleshoot Notetaker using history events”

The Notetaker history endpoints give you a complete, ordered timeline of everything that happened to a specific bot so you can see the journey it’s taken.

Call the history endpoint

Section titled “Call the history endpoint”

Use your Nylas API key and the Notetaker ID from an API response or webhook notification.

The data.events array is ordered most recent first. Each item represents a snapshot of the Notetaker bot at a specific point in time, with:

  • created_at: When the event was recorded (Unix timestamp, in seconds).
  • event_type: The kind of change that occurred (notetaker.created, notetaker.updated, notetaker.meeting_state, notetaker.media, or notetaker.deleted).
  • data: The Notetaker payload at that moment, including fields such as state, meeting_state, and (for media events) a media object.

Use history events to debug common issues

Section titled “Use history events to debug common issues”

  • Notetaker never joined the meeting

    • Look for a notetaker.created event to confirm the bot was scheduled.
    • Check later notetaker.meeting_state events:
      • Repeated connecting or a final failed_entry value usually indicates a join or lobby issue on the meeting provider side.
      • If there are no notetaker.meeting_state events at all, verify that the meeting link is valid and the join_time is correct.

  • Notetaker left the meeting earlier than expected

    • Find the last notetaker.meeting_state event where data.meeting_state might be left_meeting, disconnected, or api_request.
    • Compare the created_at timestamp to your expected meeting duration to see whether the call ended early or the bot was removed.

  • Media or transcripts never arrived

    • Confirm that there is at least one notetaker.meeting_state event showing the bot in an attending or recording_started state.
    • Look for a notetaker.media event:
      • If present, inspect the data.media object for links to recording, transcript, summary, and action_items, and check whether your project downloaded them.
      • If there is no notetaker.media event, the recording or processing likely failed; you can share the full history payload with Nylas Support for further investigation.

  • Configuration or scheduling changed unexpectedly

    • Review notetaker.updated events to see how fields such as join_time, meeting_link, or meeting_settings changed over time.
    • Because events are most recent first, you can step backwards through the array to reconstruct exactly how the Notetaker configuration evolved.