matrix-spec-proposals/content/client-server-api/modules/server_notices.md

type
module

Server Notices

Homeserver hosts often want to send messages to users in an official capacity, or have resource limits which affect a user's ability to use the homeserver. For example, the homeserver may be limited to a certain number of active users per month and has exceeded that limit. To communicate this failure to users, the homeserver would use the Server Notices room.

The aesthetics of the room (name, topic, avatar, etc) are left as an implementation detail. It is recommended that the homeserver decorate the room such that it looks like an official room to users.

Events

Notices are sent to the client as normal m.room.message events with a msgtype of m.server_notice in the server notices room. Events with a m.server_notice msgtype outside of the server notice room must be ignored by clients.

The specified values for server_notice_type are:

m.server_notice.usage_limit_reached The server has exceeded some limit which requires the server administrator to intervene. The limit_type describes the kind of limit reached. The specified values for limit_type are:

monthly_active_user The server's number of active users in the last 30 days has exceeded the maximum. New connections are being refused by the server. What defines "active" is left as an implementation detail, however servers are encouraged to treat syncing users as "active".

{{% event event="m.room.message$m.server_notice" %}}

Client behaviour

Clients can identify the server notices room by the m.server_notice tag on the room. Active notices are represented by the pinned events in the server notices room. Server notice events pinned in that room should be shown to the user through special UI and not through the normal pinned events interface in the client. For example, clients may show warning banners or bring up dialogs to get the user's attention. Events which are not server notice events and are pinned in the server notices room should be shown just like any other pinned event in a room.

The client must not expect to be able to reject an invite to join the server notices room. Attempting to reject the invite must result in a M_CANNOT_LEAVE_SERVER_NOTICE_ROOM error. Servers should not prevent the user leaving the room after joining the server notices room, however the same error code must be used if the server will prevent leaving the room.

Server behaviour

Servers should manage exactly 1 server notices room per user. Servers must identify this room to clients with the m.server_notice tag. Servers should invite the target user rather than automatically join them to the server notice room.

How servers send notices to clients, and which user they use to send the events, is left as an implementation detail for the server.