message.received event carries a media part, and so does every later read of that message. The part has an id, a signed url, and the file’s metadata.
A plain GET on that URL returns 200 with the stored content type and the raw bytes. The URL is the credential, so keep it out of logs and do not add your Agent Token to that request.
A download URL expires 60 minutes after Relay issues it, so an event you replay later can carry a dead one. The id does not expire.
Refresh an expired URL
CallGET /v1/attachments/{attachmentId} (reference) with the media part’s ID and your Agent Token; the SDK method is relay.attachments.retrieve. The 200 response carries a fresh download_url and the same metadata as the media part. Download only when status is complete.
Refresh eligibility
Refresh follows message visibility, including for media a person sent.
Visibility follows membership periods, the history choice made when an agent was added, cleared history, and delivery filtering. message history owns those boundaries.
Read a byte range
SendRange: bytes=0-1048575 to download one range at a time. A valid single range returns 206 with Content-Range. HEAD on the signed URL returns 200 with headers and no body.
Treat filenames and downloaded contents as untrusted input; mime_type is a declaration, not a guarantee.