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 fresh URLs after that, call the Get Notetaker Media endpoint, which issues new URLs with a fresh 60-minute window every time. 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": 1737500935555,
  "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 fresh ones. The endpoint is read-only and idempotent, so you can call it as often as you need without side effects.

The endpoint only returns media when the Notetaker’s state is media_available, and the response includes every media type that was enabled in notetaker_settings at the time of the meeting. A 404 means media is still processing; a 410 means it’s already been deleted. See Media or transcripts never arrived for how to tell the cases apart.

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.