← Back to PRs

#10313: fix(matrix): fallback to authenticated media download (Matrix v1.11+)

by iter-next open 2026-02-06 09:52 View on GitHub →
channel: matrix stale
## What Adds a fallback to the Matrix authenticated media download endpoint when the standard SDK download method fails. ## Why Matrix homeservers running Synapse 1.85+ / spec v1.11+ can enforce authenticated media downloads. When enabled, the legacy `/_matrix/media/v3/download/` endpoint returns 403 Forbidden, causing all media (voice messages, images, files) to silently fail. The `@vector-im/matrix-bot-sdk`'s `downloadContent()` uses the legacy endpoint internally. ## How When `client.downloadContent()` throws (e.g. 403 from authenticated media enforcement), the code now: 1. Parses the `mxc://` URL to extract server name and media ID 2. Constructs the authenticated endpoint URL: `/_matrix/client/v1/media/download/{serverName}/{mediaId}` 3. Makes the request with the bot's access token in the Authorization header 4. Falls back to the original error if the authenticated download also fails ## Testing - Tested against a Synapse instance with authenticated media enabled - Voice messages (audio/ogg) download and transcribe correctly - Standard (non-authenticated) servers still work (fallback is only triggered on error) - No regressions observed for encrypted media (separate code path) <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> - Updates Matrix unencrypted media downloads to retry via the Matrix v1.11 authenticated media download endpoint when the SDK’s legacy `downloadContent()` fails. - Parses `mxc://` URLs to build a `/_matrix/client/v1/media/download/{server}/{mediaId}` request using the bot access token. - Keeps existing encrypted-media handling unchanged and continues enforcing `maxBytes` limits on downloaded content. <h3>Confidence Score: 3/5</h3> - This PR is mostly safe to merge, but the fallback URL construction has a concrete edge-case bug and error handling semantics changed in a way that can misreport failures. - Core behavior is straightforward and isolated to one file, but the authenticated fallback interpolates unencoded MXC parts into the path (can break downloads for certain MXC URLs) and the catch block now alters error reporting for all failures, not just authenticated-media 403s. - extensions/matrix/src/matrix/monitor/media.ts <!-- greptile_other_comments_section --> <sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub> <!-- /greptile_comment -->

Most Similar PRs