# Media repository callbacks - Synapse

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Media repository callbacks

Media repository callbacks allow module developers to customise the behaviour of the media repository on a per user basis. Media repository callbacks can be registered using the module API’s `register_media_repository_callbacks` method.

The available media repository callbacks are:

### `get_media_config_for_user`

First introduced in Synapse v1.132.0

    async def get_media_config_for_user(user_id: str) -> JsonDict | None

Caution: This callback is currently experimental . The method signature or behaviour may change without notice.

Called when processing a request from a client for the media config endpoint.

The arguments passed to this callback are:

- `user_id`: The Matrix user ID of the user (e.g. `@alice:example.com`) making the request.

If the callback returns a dictionary then it will be used as the body of the response to the client.

If multiple modules implement this callback, they will be considered in order. If a callback returns `None`, Synapse falls through to the next one. The value of the first callback that does not return `None` will be used. If this happens, Synapse will not call any of the subsequent implementations of this callback.

If no module returns a non-`None` value then the default media config will be returned.

### `is_user_allowed_to_upload_media_of_size`

First introduced in Synapse v1.132.0

    async def is_user_allowed_to_upload_media_of_size(user_id: str, size: int) -> bool

Caution: This callback is currently experimental . The method signature or behaviour may change without notice.

Called before media is accepted for upload from a user, in case the module needs to enforce a different limit for the particular user.

The arguments passed to this callback are:

- `user_id`: The Matrix user ID of the user (e.g. `@alice:example.com`) making the request.
- `size`: The size in bytes of media that is being requested to upload.

If the module returns `False`, the current request will be denied with the error code `M_TOO_LARGE` and the HTTP status code 413.

If multiple modules implement this callback, they will be considered in order. If a callback returns `True`, Synapse falls through to the next one. The value of the first callback that returns `False` will be used. If this happens, Synapse will not call any of the subsequent implementations of this callback.

### `get_media_upload_limits_for_user`

First introduced in Synapse v1.139.0

    async def get_media_upload_limits_for_user(user_id: str, size: int) -> list[synapse.module_api.MediaUploadLimit] | None

Caution: This callback is currently experimental. The method signature or behaviour may change without notice.

Called when processing a request to store content in the media repository. This can be used to dynamically override the media upload limits configuration.

The arguments passed to this callback are:

- `user_id`: The Matrix user ID of the user (e.g. `@alice:example.com`) making the request.

If the callback returns a list then it will be used as the limits instead of those in the configuration (if any).

If an empty list is returned then no limits are applied (warning: users will be able to upload as much data as they desire).

If multiple modules implement this callback, they will be considered in order. If a callback returns `None`, Synapse falls through to the next one. The value of the first callback that does not return `None` will be used. If this happens, Synapse will not call any of the subsequent implementations of this callback.

If there are no registered modules, or if all modules return `None`, then the default media upload limits configuration will be used.

### `on_media_upload_limit_exceeded`

First introduced in Synapse v1.139.0

    async def on_media_upload_limit_exceeded(user_id: str, limit: synapse.module_api.MediaUploadLimit, sent_bytes: int, attempted_bytes: int) -> None

Caution: This callback is currently experimental. The method signature or behaviour may change without notice.

Called when a user attempts to upload media that would exceed a configured media upload limit.

This callback will only be called on workers which handle POST /_matrix/media/v3/upload requests.

This could be used to inform the user that they have reached a media upload limit through some external method.

The arguments passed to this callback are:

- `user_id`: The Matrix user ID of the user (e.g. `@alice:example.com`) making the request.
- `limit`: The `synapse.module_api.MediaUploadLimit` representing the limit that was reached.
- `sent_bytes`: The number of bytes already sent during the period of the limit.
- `attempted_bytes`: The number of bytes that the user attempted to send.