Skip to content
Skip to main content

Handling Notetaker media files

Last updated:

After Notetaker leaves a meeting, Nylas takes a few minutes to process the recording, then sends a notetaker.media webhook notification with a download URL for each file: the recording, a thumbnail, the transcript, and, when enabled, the summary and action items. Which files you get depends on the notetaker_settings in effect for that meeting. For the shape of each file, see Notetaker media formats.

How Nylas delivers media files

Section titled “How Nylas delivers media files”

Nylas delivers media files through temporary, pre-authenticated download URLs. When media processing completes, it generates a unique URL for each file and includes them in the notetaker.media webhook notification. The URLs authorize access to the file directly, with no additional authentication, so you can pass one to any HTTP client without your API key or grant credentials.

Each URL is valid for 60 minutes from the time it was generated, then expires and any download attempt returns an error. This is a deliberate security constraint: a short window limits the exposure if a URL is ever logged or leaked. To get current URLs after that, call the Get Notetaker Media endpoint. It returns each file’s existing URL while that URL is still valid, and a new URL with a 60-minute window once the old one has expired. See Regenerate expired media URLs.

Every URL is scoped to a single file, is served over HTTPS, and doesn’t contain or expose your API key, grant tokens, or account identifiers. Nylas doesn’t issue persistent download tokens or reuse expired URLs, and once the retention window passes, previously generated URLs for those files stop working.

Media response fields

Section titled “Media response fields”

When you call the Get Notetaker Media endpoint, each media object in the response includes metadata alongside the download URL:

FieldDescription
urlPre-authenticated download URL, valid for 60 minutes from generation.
created_atWhen the file was created, as a Unix timestamp in seconds.
expires_atWhen the file will be permanently deleted from Nylas servers, as a Unix timestamp in seconds.
ttlSeconds remaining until the file is deleted. This is the difference between expires_at and the time of your request.
sizeFile size in bytes.
typeMIME type (for example, video/mp4, application/json, image/png).
nameFile name.
durationRecording duration in seconds (recording only).

Download and store Notetaker media files

Section titled “Download and store Notetaker media files”

The reliable pattern is to subscribe to notetaker.media webhook notifications and download each file as soon as its state is available, before the 60-minute URL window closes. Store the files in your own infrastructure and present them to your users from there. Add retry logic for failed downloads, and plan for concurrency: an application with many users can receive thousands of media webhooks per day, each carrying up to 5 files.

{
  "specversion": "1.0",
  "type": "notetaker.media",
  "source": "/nylas/notetaker",
  "id": "<WEBHOOK_ID>",
  "time": 1737500935,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "object": {
      "id": "<NOTETAKER_ID>",
      "grant_id": "<NYLAS_GRANT_ID>",
      "object": "notetaker",
      "meeting_settings": {
        "video_recording": true,
        "audio_recording": true,
        "transcription": true,
        "transcription_settings": {
          "expected_languages": ["en", "es"],
          "fallback_language": "en"
        },
        "summary": true,
        "summary_settings": {
          "custom_instructions": "Focus on action items related to the product launch."
        },
        "action_items": true,
        "action_items_settings": {
          "custom_instructions": "Group action items by team member."
        },
        "leave_after_silence_seconds": 300,
        "messages": {
          "on_join": [
            {
              "type": "text",
              "content": "👋 Hey team! I'm your AI notetaker — here to capture the key points.",
              "send_after_ms": 5000
            }
          ],
          "on_participant_join": [
            {
              "type": "text",
              "content": "👋 Welcome! Recording and transcription are running.",
              "debounce_ms": 3000
            }
          ]
        }
      },
      "meeting_provider": "Google Meet",
      "meeting_link": "https://meet.google.com/abc-defg-hij",
      "join_time": 1737500936450,
      "event": {
        "ical_uid": "<ICAL_UID>",
        "event_id": "<EVENT_ID>",
        "master_event_id": "<MASTER_EVENT_ID>"
      },
      "status": "available",
      "state": "available",
      "media": {
        "recording": "<SIGNED_URL>",
        "recording_duration": "1800",
        "recording_file_format": "mp4",
        "thumbnail": "<SIGNED_URL>",
        "transcript": "<SIGNED_URL>",
        "summary": "<SIGNED_URL>",
        "action_items": "<SIGNED_URL>",
        "retained_until": 1738710000
      }
    }
  }
}

If you’d rather not keep media on Nylas at all once you’ve copied it, delete the Notetaker at the end of your download pipeline.

Regenerate expired media URLs

Section titled “Regenerate expired media URLs”

If you don’t download media files within 60 minutes of the webhook notification, the URLs expire. Call the Get Notetaker Media endpoint to get current ones. The endpoint is read-only and idempotent, so you can call it as often as you need without side effects.

The endpoint returns media only when it’s ready: media_available in a Get Notetaker response, or available in webhooks. The response includes every media type enabled in notetaker_settings at the time of the meeting, except a summary or action items that Nylas couldn’t generate (see Handle a summary or action items that failed).

A 404 means media isn’t available. Check the Notetaker’s state to see why: media_processing (processing in webhooks) means Nylas is still processing it, and media_error means processing failed. A 410 means the media was deleted or the bot never joined the meeting. See Media or transcripts never arrived.

Handle a summary or action items that failed

Section titled “Handle a summary or action items that failed”

When Nylas can’t generate a summary or action items you enabled, Get Notetaker Media returns 207 Multi-Status instead of 200. The response still includes every file Nylas generated, so you can download the recording and transcript as usual. Each summary or action items file Nylas couldn’t generate is listed in data.errors.

In this example, the summary failed and the other files are available. Each errors entry has an artifact (summary or action_items) and a code. The only code is generation_failed. This example leaves out the other file fields.

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "action_items": { "name": "meeting_action_items.json", "url": "<SIGNED_URL>" },
    "recording": { "name": "meeting_recording.mp4", "url": "<SIGNED_URL>" },
    "transcript": { "name": "transcript.json", "url": "<SIGNED_URL>" },
    "errors": [{ "artifact": "summary", "code": "generation_failed" }]
  }
}

Check your integration:

  • Treat any 2xx as success. Code that accepts only 200 treats a 207 as a failed request and drops the files that did arrive.
  • Upgrade the Nylas Ruby SDK to v6.9.0 or later. Earlier versions raise an error on 207. The Node.js and Python SDKs already accept it.
  • Skip errors when you loop over data. It’s a list, not a file, so it has no url.
  • Webhooks carry the same list. The notetaker.media notification includes it as media.errors. Delivery is unchanged.

Media processed before Nylas started reporting these failures has no errors list, so it can return 200 without a summary or action items.

Calling the endpoint again doesn’t retry generation. When Nylas generates every file you enabled, the response is 200 with no errors.

Delete a Notetaker and its media

Section titled “Delete a Notetaker and its media”

You don’t have to wait for the retention window to expire. Once your system has retrieved and stored all the files, call the DELETE /v3/notetakers/<NOTETAKER_ID> or DELETE /v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID> endpoint to remove the Notetaker and every file it produced from Nylas right away. Data-conscious applications automate this as the last step of the download pipeline so sensitive meeting content spends minutes, not 14 days, on third-party infrastructure.

Deletion is permanent and can’t be undone by you or by Nylas Support. For the full behavior and the notetaker.deleted webhook, see Delete a Notetaker.