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

type
module

Room Tagging

Users can add tags to rooms. Tags are namespaced strings used to label rooms. A room may have multiple tags. Tags are only visible to the user that set them but are shared across all their devices.

Events

The tags on a room are received as single m.tag event in the account_data section of a room. The content of the m.tag event is a tags key whose value is an object mapping the name of each tag to another object.

The JSON object associated with each tag gives information about the tag, e.g how to order the rooms with a given tag.

Ordering information is given under the order key as a number between 0 and 1. The numbers are compared such that 0 is displayed first. Therefore a room with an order of 0.2 would be displayed before a room with an order of 0.7. If a room has a tag without an order key then it should appear after the rooms with that tag that have an order key.

The name of a tag MUST NOT exceed 255 bytes.

The tag namespace is defined as follows:

• The namespace m.* is reserved for tags defined in the Matrix specification. Clients must ignore any tags in this namespace they don't understand.
• The namespace u.* is reserved for user-defined tags. The portion of the string after the u. is defined to be the display name of this tag. No other semantics should be inferred from tags in this namespace.
• A client or app willing to use special tags for advanced functionality should namespace them similarly to state keys: tld.name.*
• Any tag in the tld.name.* form but not matching the namespace of the current client should be ignored
• Any tag not matching the above rules should be interpreted as a user tag from the u.* namespace, as if the name had already had u. stripped from the start (ie. the name of the tag is used as the display name directly). These non-namespaced tags are supported for historical reasons. New tags should use one of the defined namespaces above.

Several special names are listed in the specification: The following tags are defined in the m.* namespace:

• m.favourite: The user's favourite rooms. These should be shown with higher precedence than other rooms.
• m.lowpriority: These should be shown with lower precedence than others.
• m.server_notice: Used to identify Server Notice Rooms.

{{% event event="m.tag" %}}

Client Behaviour

{{% http-api spec="client-server" api="tags" %}}