mautrix.client.api package

Submodules

mautrix.client.api.base module

class mautrix.client.api.base.BaseClientAPI(mxid: NewType.<locals>.new_type, api: mautrix.api.http.HTTPAPI = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, *args, **kwargs)[source]

Bases: object

BaseClientAPI is the base class for ClientAPI. This is separate from the main ClientAPI class so that the ClientAPI methods can be split into multiple classes (that inherit this class).All those section-specific method classes are inherited by the main ClientAPI class to create the full class.

classmethod parse_mxid(mxid: NewType.<locals>.new_type) → Tuple[str, str][source]
Return type:Tuple[str, str]
classmethod parse_user_id(mxid: NewType.<locals>.new_type) → Tuple[str, str][source]

Parse the localpart and server name from a Matrix user ID.

Parameters:mxid (UserID[str]) – The Matrix user ID.
Return type:Tuple[str, str]
Returns:A tuple of (localpart, server_name).
Raises:ValueError – if the given user ID is invalid.
set_mxid(mxid: NewType.<locals>.new_type) → None[source]

Update the Matrix user ID used by this ClientAPI.

Parameters:mxid (UserID[str]) – The new Matrix user ID.
Return type:None

mautrix.client.api.client module

class mautrix.client.api.client.ClientAPI(mxid: NewType.<locals>.new_type, api: mautrix.api.http.HTTPAPI = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, *args, **kwargs)[source]

Bases: mautrix.client.api.authentication.ClientAuthenticationMethods, mautrix.client.api.filtering.FilteringMethods, mautrix.client.api.events.EventMethods, mautrix.client.api.rooms.RoomMethods, mautrix.client.api.user_data.UserDataMethods, mautrix.client.api.modules.ModuleMethods

ClientAPI is a medium-level wrapper around the HTTPAPI that provides many easy-to-use functions for accessing the client-server API.

mautrix.client.api.events module

class mautrix.client.api.events.EventMethods(mxid: NewType.<locals>.new_type, api: mautrix.api.http.HTTPAPI = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, *args, **kwargs)[source]

Bases: mautrix.client.api.base.BaseClientAPI

Methods in section 8 Events of the spec. Includes /syncing, getting messages and state, setting state, sending messages and redacting messages.

See also: API reference

get_event(room_id: NewType.<locals>.new_type, event_id: NewType.<locals>.new_type) → NewType.<locals>.new_type[source]

Get a single event based on room_id/event_id. You must have permission to retrieve this event e.g. by being a member in the room for this event.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room the event is in.
  • event_id (EventID[str]) – The event ID to get.
Return type:

Event[Union[MessageEvent, ReactionEvent, RedactionEvent, StateEvent, ReceiptEvent, PresenceEvent, TypingEvent, GenericEvent]]
Returns:

The event.
get_joined_members(room_id: NewType.<locals>.new_type) → Dict[NewType.<locals>.new_type, mautrix.client.api.types.users.Member][source]

Get a user ID -> member info map for a room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS’s users must be in the room. This API is primarily for Application Services and should be faster to respond than /members as it can be implemented more efficiently on the server.

See also: API reference

Parameters:room_id (RoomID[str]) – The ID of the room to get the members of.
Return type:Dict[UserID[str], Member]
Returns:A dictionary from user IDs to Member info objects.
get_members(room_id: NewType.<locals>.new_type) → List[mautrix.client.api.types.event.state.StateEvent][source]

Get the list of members for a room.

See also: API reference

Parameters:room_id (RoomID[str]) – The ID of the room to get the member events for.
Return type:List[StateEvent]
Returns:A list of most recent member events for each user.
get_messages(room_id: NewType.<locals>.new_type, direction: mautrix.client.api.types.misc.PaginationDirection, from_token: NewType.<locals>.new_type, to_token: Optional[NewType.<locals>.new_type] = None, limit: Optional[int] = None, filter_json: Optional[str] = None) → mautrix.client.api.types.misc.PaginatedMessages[source]

Get a list of message and state events for a room. Pagination parameters are used to paginate history in the room.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room to get events from.
  • direction (PaginationDirection) – The direction to return events from.
  • from_token (SyncToken[str]) – The token to start returning events from. This token can be obtained from a prev_batch token returned for each room by the sync endpoint, or from a start or end token returned by a previous request to this endpoint.
  • to_token (Optional[SyncToken[str]]) – The token to stop returning events at.
  • limit (Optional[int]) – The maximum number of events to return. Defaults to 10.
  • filter_json (Optional[str]) – A JSON RoomEventFilter to filter returned events with.

Returns:

Return type:PaginatedMessages
get_state(room_id: NewType.<locals>.new_type) → List[mautrix.client.api.types.event.state.StateEvent][source]

Get the state events for the current state of a room.

See also: API reference

Parameters:room_id (RoomID[str]) – The ID of the room to look up the state for.
Return type:List[StateEvent]
Returns:A list of state events with the most recent of each event_type/state_key pair.
get_state_event(room_id: NewType.<locals>.new_type, event_type: mautrix.client.api.types.event.base.EventType, state_key: Optional[str] = None) → Union[mautrix.client.api.types.event.state.PowerLevelStateEventContent, mautrix.client.api.types.event.state.MemberStateEventContent, mautrix.client.api.types.event.state.AliasesStateEventContent, mautrix.client.api.types.event.state.CanonicalAliasStateEventContent, mautrix.client.api.types.event.state.RoomNameStateEventContent, mautrix.client.api.types.event.state.RoomAvatarStateEventContent, mautrix.client.api.types.event.state.RoomTopicStateEventContent, mautrix.client.api.types.event.state.RoomPinnedEventsStateEventContent, mautrix.client.api.types.event.state.RoomTombstoneEventContent, mautrix.client.api.types.util.obj.Obj][source]

Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room to look up the state in.
  • event_type (EventType) – The type of state to look up.
  • state_key (Optional[str]) – The key of the state to look up. Defaults to empty string.
Return type:

Union[PowerLevelStateEventContent, MemberStateEventContent, AliasesStateEventContent, CanonicalAliasStateEventContent, RoomNameStateEventContent, RoomAvatarStateEventContent, RoomTopicStateEventContent, RoomPinnedEventsStateEventContent, RoomTombstoneEventContent, Obj]
Returns:

The state event.
react(room_id: NewType.<locals>.new_type, event_id: NewType.<locals>.new_type, key: str) → Awaitable[None][source]
Return type:Awaitable[None]
redact(room_id: NewType.<locals>.new_type, event_id: NewType.<locals>.new_type, reason: Optional[str] = '', **kwargs) → NewType.<locals>.new_type[source]

Send an event to redact a previous event.

Redacting an event strips all information out of an event which isn’t critical to the integrity of the server-side representation of the room.

This cannot be undone.

Users may redact their own events, and any user with a power level greater than or equal to the redact power level of the room may redact events there.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room the event is in.
  • event_id (EventID[str]) – The ID of the event to redact.
  • reason (Optional[str]) – The reason for the event being redacted.
  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method. Used by the IntentAPI to pass timestamp massaging and external URL fields to AppServiceAPI.request().
Return type:

EventID[str]
Returns:

The ID of the event that was sent to redact the other event.
send_emote(room_id: NewType.<locals>.new_type, text: str, html: Optional[str] = None, relates_to: Optional[mautrix.client.api.types.event.message.RelatesTo] = None, **kwargs) → Awaitable[NewType.<locals>.new_type][source]

Send an emote to a room. Emotes are usually displayed by prepending a star and the user’s display name to the message, which means they’re usually written in the third person.

Parameters:
  • room_id (RoomID[str]) – The ID of the room to send the message to.
  • text (str) – The text to send. If set to None, the given HTML is used instead.
  • html (Optional[str]) – The HTML to send.
  • msgtype – The message type to send. Defaults to MessageType.TEXT (normal text message)
  • relates_to (Optional[RelatesTo]) – Message relation metadata used for things like replies.
  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method.
Return type:

Awaitable[EventID[str]]
Returns:

The ID of the event that was sent.
send_file(room_id: NewType.<locals>.new_type, url: NewType.<locals>.new_type, info: Optional[mautrix.client.api.types.event.message.BaseFileInfo] = None, file_name: str = None, file_type: <unknown>.MessageType = m.file, relates_to: Optional[mautrix.client.api.types.event.message.RelatesTo] = None, **kwargs) → Awaitable[NewType.<locals>.new_type][source]

Send a file to a room.

Parameters:
  • room_id (RoomID[str]) – The ID of the room to send the message to.
  • url (ContentURI[str]) – The Matrix content repository URI of the file. You can upload files using MediaRepositoryMethods.upload_media().
  • info (Optional[BaseFileInfo]) – Additional metadata about the file, e.g. mimetype, image size, video duration, etc
  • file_name (Optional[str]) – The name for the file to send.
  • file_type (MessageType) – The general file type to send. The file type can be further specified by setting the mimetype field of the info parameter. Defaults to MessageType.FILE (unspecified file type, e.g. document)
  • relates_to (Optional[RelatesTo]) – Message relation metadata used for things like replies.
  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method.
Return type:

Awaitable[EventID[str]]
Returns:

The ID of the event that was sent.
send_image(room_id: NewType.<locals>.new_type, url: NewType.<locals>.new_type, info: Optional[mautrix.client.api.types.event.message.ImageInfo] = None, file_name: str = None, relates_to: Optional[mautrix.client.api.types.event.message.RelatesTo] = None, **kwargs) → Awaitable[NewType.<locals>.new_type][source]

Send an image to a room.

Parameters:
  • room_id (RoomID[str]) – The ID of the room to send the message to.
  • url (ContentURI[str]) – The Matrix content repository URI of the image. You can upload files using MediaRepositoryMethods.upload_media().
  • info (Optional[ImageInfo]) – Additional metadata about the image, e.g. mimetype and image size
  • file_name (Optional[str]) – The file name for the image to send.
  • relates_to (Optional[RelatesTo]) – Message relation metadata used for things like replies.
  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method.
Return type:

Awaitable[EventID[str]]
Returns:

The ID of the event that was sent.
send_message(room_id: NewType.<locals>.new_type, content: Union[mautrix.client.api.types.event.message.TextMessageEventContent, mautrix.client.api.types.event.message.MediaMessageEventContent, mautrix.client.api.types.event.message.LocationMessageEventContent, mautrix.client.api.types.util.obj.Obj], **kwargs) → Awaitable[NewType.<locals>.new_type][source]

Send a message to a room.

Parameters:
Return type:

Awaitable[EventID[str]]
Returns:

The ID of the event that was sent.
send_message_event(room_id: NewType.<locals>.new_type, event_type: mautrix.client.api.types.event.base.EventType, content: Union[mautrix.client.api.types.event.message.TextMessageEventContent, mautrix.client.api.types.event.message.MediaMessageEventContent, mautrix.client.api.types.event.message.LocationMessageEventContent, mautrix.client.api.types.util.obj.Obj, mautrix.client.api.types.event.redaction.RedactionEventContent, mautrix.client.api.types.event.reaction.ReactionEventContent, mautrix.client.api.types.event.state.PowerLevelStateEventContent, mautrix.client.api.types.event.state.MemberStateEventContent, mautrix.client.api.types.event.state.AliasesStateEventContent, mautrix.client.api.types.event.state.CanonicalAliasStateEventContent, mautrix.client.api.types.event.state.RoomNameStateEventContent, mautrix.client.api.types.event.state.RoomAvatarStateEventContent, mautrix.client.api.types.event.state.RoomTopicStateEventContent, mautrix.client.api.types.event.state.RoomPinnedEventsStateEventContent, mautrix.client.api.types.event.state.RoomTombstoneEventContent, mautrix.client.api.types.event.account_data.RoomTagAccountDataEventContent, Dict[NewType.<locals>.new_type, Dict[<unknown>.ReceiptType, Dict[NewType.<locals>.new_type, mautrix.client.api.types.event.ephemeral.SingleReceiptEventContent]]], mautrix.client.api.types.event.ephemeral.TypingEventContent], **kwargs) → NewType.<locals>.new_type[source]

Send a message event to a room. Message events allow access to historical events and pagination, making them suited for “once-off” activity in a room.

See also: API reference

Parameters:
Return type:

EventID[str]
Returns:

The ID of the event that was sent.
send_notice(room_id: NewType.<locals>.new_type, text: str, html: Optional[str] = None, relates_to: Optional[mautrix.client.api.types.event.message.RelatesTo] = None, **kwargs) → Awaitable[NewType.<locals>.new_type][source]

Send a notice text message to a room. Notices are like normal text messages, but usually sent by bots to tell other bots not to react to them. If you’re a bot, please send notices instead of normal text, unless there is a reason to do something else.

Parameters:
  • room_id (RoomID[str]) – The ID of the room to send the message to.
  • text (str) – The text to send. If set to None, the given HTML is used instead.
  • html (Optional[str]) – The HTML to send.
  • msgtype – The message type to send. Defaults to MessageType.TEXT (normal text message)
  • relates_to (Optional[RelatesTo]) – Message relation metadata used for things like replies.
  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method.
Return type:

Awaitable[EventID[str]]
Returns:

The ID of the event that was sent.
send_state_event(room_id: NewType.<locals>.new_type, event_type: mautrix.client.api.types.event.base.EventType, content: Union[mautrix.client.api.types.event.state.PowerLevelStateEventContent, mautrix.client.api.types.event.state.MemberStateEventContent, mautrix.client.api.types.event.state.AliasesStateEventContent, mautrix.client.api.types.event.state.CanonicalAliasStateEventContent, mautrix.client.api.types.event.state.RoomNameStateEventContent, mautrix.client.api.types.event.state.RoomAvatarStateEventContent, mautrix.client.api.types.event.state.RoomTopicStateEventContent, mautrix.client.api.types.event.state.RoomPinnedEventsStateEventContent, mautrix.client.api.types.event.state.RoomTombstoneEventContent, mautrix.client.api.types.util.obj.Obj], state_key: Optional[str] = '', **kwargs) → NewType.<locals>.new_type[source]

Send a state event to a room. State events with the same room_id, event_type and state_key will be overridden.

See also: API reference

Parameters:
Return type:

EventID[str]
Returns:

The ID of the event that was sent.
send_sticker(room_id: NewType.<locals>.new_type, url: NewType.<locals>.new_type, info: Optional[mautrix.client.api.types.event.message.ImageInfo], text: Optional[str] = '', relates_to: Optional[mautrix.client.api.types.event.message.RelatesTo] = None, **kwargs) → Awaitable[NewType.<locals>.new_type][source]

Send a sticker to a room. Stickers are basically images, but they’re usually rendered slightly differently.

Parameters:
  • room_id (RoomID[str]) – The ID of the room to send the message to.
  • url (ContentURI[str]) – The Matrix content repository URI of the sticker. You can upload files using MediaRepositoryMethods.upload_media().
  • info (Optional[ImageInfo]) – Additional metadata about the sticker, e.g. mimetype and image size
  • text (Optional[str]) – A textual description of the sticker.
  • relates_to (Optional[RelatesTo]) – Message relation metadata used for things like replies.
  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method.
Return type:

Awaitable[EventID[str]]
Returns:

The ID of the event that was sent.
send_text(room_id: NewType.<locals>.new_type, text: str, html: Optional[str] = None, msgtype: <unknown>.MessageType = m.text, relates_to: Optional[mautrix.client.api.types.event.message.RelatesTo] = None, **kwargs) → Awaitable[NewType.<locals>.new_type][source]

Send a text message to a room.

Parameters:
  • room_id (RoomID[str]) – The ID of the room to send the message to.
  • text (str) – The text to send. If set to None, the given HTML is used instead.
  • html (Optional[str]) – The HTML to send.
  • msgtype (MessageType) – The message type to send. Defaults to MessageType.TEXT (normal text message)
  • relates_to (Optional[RelatesTo]) – Message relation metadata used for things like replies.
  • **kwargs – Optional parameters to pass to the HTTPAPI.request() method.
Return type:

Awaitable[EventID[str]]
Returns:

The ID of the event that was sent.
sync(since: NewType.<locals>.new_type = None, timeout: int = 30000, filter_id: NewType.<locals>.new_type = None, full_state: bool = False, set_presence: <unknown>.PresenceState = None) → Awaitable[NewType.<locals>.new_type][source]

Perform a sync request.

See also: API reference

Parameters:
  • since (str) – Optional. A token which specifies where to continue a sync from.
  • timeout (int) – Optional. The time in milliseconds to wait.
  • filter_id (int) – A filter ID.
  • full_state (bool) – Return the full state for every room the user has joined Defaults to false.
  • set_presence (str) – Should the client be marked as “online” or” offline”
Return type:

Awaitable[JSON[Union[str, int, float, None, Dict[str, _Forwardref], List[_Forwardref]]]]

mautrix.client.api.filtering module

class mautrix.client.api.filtering.FilteringMethods(mxid: NewType.<locals>.new_type, api: mautrix.api.http.HTTPAPI = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, *args, **kwargs)[source]

Bases: mautrix.client.api.base.BaseClientAPI

Methods in section 7 Filtering of the spec.

Filters can be created on the server and can be passed as as a parameter to APIs which return events. These filters alter the data returned from those APIs. Not all APIs accept filters.

See also: API reference

create_filter(filter_params: mautrix.client.api.types.filter.Filter) → NewType.<locals>.new_type[source]

Upload a new filter definition to the homeserver.

See also: API reference

Parameters:filter_params (Filter) – The filter data.
Return type:FilterID[str]
Returns:A filter ID that can be used in future requests to refer to the uploaded filter.
get_filter(filter_id: NewType.<locals>.new_type) → mautrix.client.api.types.filter.Filter[source]

Download a filter.

See also: API reference

Parameters:filter_id (FilterID[str]) – The filter ID to download.
Return type:Filter
Returns:The filter data.

mautrix.client.api.rooms module

class mautrix.client.api.rooms.RoomMethods(mxid: NewType.<locals>.new_type, api: mautrix.api.http.HTTPAPI = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, *args, **kwargs)[source]

Bases: mautrix.client.api.base.BaseClientAPI

Methods in section 9 Rooms of the spec. These methods are used for creating rooms, interacting with the room directory and using the easy room metadata editing endpoints. Generic state setting and sending events are in the :EventMethods: (section 8) module.

See also: API reference

add_room_alias(room_id: NewType.<locals>.new_type, alias_localpart: str, override: bool = False) → None[source]

Create a new mapping from room alias to room ID.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The room ID to set.
  • alias_localpart (str) – The localpart of the room alias to set.
  • override (bool) – Whether or not the alias should be removed and the request retried if the server responds with HTTP 409 Conflict
Return type:

None
ban_user(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type, reason: Optional[str] = '') → None[source]

Ban a user in the room. If the user is currently in the room, also kick them. When a user is banned from a room, they may not join it or be invited to it until they are unbanned. The caller must have the required power level in order to perform this operation.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room from which the user should be banned.
  • user_id (UserID[str]) – The fully qualified user ID of the user being banned.
  • reason (Optional[str]) – The reason the user has been kicked. This will be supplied as the reason on the target’s updated m.room.member event.
Return type:

None
create_room(alias_localpart: Optional[str] = None, visibility: mautrix.client.api.types.misc.RoomDirectoryVisibility = <RoomDirectoryVisibility.PRIVATE: 'private'>, preset: mautrix.client.api.types.misc.RoomCreatePreset = <RoomCreatePreset.PRIVATE: 'private_chat'>, name: Optional[str] = None, topic: Optional[str] = None, is_direct: bool = False, invitees: Optional[List[NewType.<locals>.new_type]] = None, initial_state: Optional[List[Union[mautrix.client.api.types.event.state.StateEvent, Dict]]] = None, room_version: str = None, creation_content: NewType.<locals>.new_type = None) → NewType.<locals>.new_type[source]

Create a new room with various configuration options.

See also: API reference

Parameters:
  • alias_localpart (Optional[str]) – The desired room alias local part. If this is included, a room alias will be created and mapped to the newly created room. The alias will belong on the same homeserver which created the room. For example, if this was set to “foo” and sent to the homeserver “example.com” the complete room alias would be #foo:example.com.
  • visibility (RoomDirectoryVisibility) – A public visibility indicates that the room will be shown in the published room list. A private visibility will hide the room from the published room list. Defaults to private. NB: This should not be confused with join_rules which also uses the word public.
  • preset (RoomCreatePreset) – Convenience parameter for setting various default state events based on a preset. Defaults to private (invite-only).
  • name (Optional[str]) – If this is included, an m.room.name event will be sent into the room to indicate the name of the room. See Room Events for more information on m.room.name.
  • topic (Optional[str]) – If this is included, an m.room.topic event will be sent into the room to indicate the topic for the room. See Room Events for more information on m.room.topic.
  • is_direct (bool) – This flag makes the server set the is_direct flag on the m.room.member events sent to the users in invite and invite_3pid. See Direct Messaging for more information.
  • invitees (Optional[List[UserID[str]]]) – A list of user IDs to invite to the room. This will tell the server to invite everyone in the list to the newly created room.
  • initial_state (Optional[List[Union[StateEvent, Dict[~KT, ~VT]]]]) –

    A list of state events to set in the new room. This allows the user to override the default state events set in the new room. The expected format of the state events are an object with type, state_key and content keys set.

    Takes precedence over events set by is_public, but gets overriden by name and topic keys.

  • room_version (Optional[str]) – The room version to set for the room. IF not provided, the homeserver will use its configured default.
  • creation_content (Optional[JSON[Union[str, int, float, None, Dict[str, _Forwardref], List[_Forwardref]]]]) – Extra keys, such as m.federate, to be added to the m.room.create event. The server will ignore creator and room_version. Future versions of the specification may allow the server to ignore other keys.
Return type:

RoomID[str]
Returns:

The ID of the newly created room.
Raises:

MatrixResponseError – If the response does not contain a room_id field.
forget_room(room_id: NewType.<locals>.new_type) → None[source]

Stop remembering a particular room, i.e. forget it.

In general, history is a first class citizen in Matrix. After this API is called, however, a user will no longer be able to retrieve history for this room. If all users on a homeserver forget a room, the room is eligible for deletion from that homeserver.

If the user is currently joined to the room, they must leave the room before calling this API.

See also: API reference

Parameters:room_id (RoomID[str]) – The ID of the room to forget.
Return type:None
get_joined_rooms() → List[NewType.<locals>.new_type][source]

Get the list of rooms the user is in.

Return type:List[RoomID[str]]
get_room_alias(room_alias: NewType.<locals>.new_type) → mautrix.client.api.types.misc.RoomAliasInfo[source]

Request the server to resolve a room alias to a room ID.

The server will use the federation API to resolve the alias if the domain part of the alias does not correspond to the server’s own domain.

See also: API reference

Parameters:room_alias (RoomAlias[str]) – The room alias.
Return type:RoomAliasInfo
Returns:The room ID and a list of servers that are aware of the room.
get_room_directory(limit: Optional[int] = None, server: Optional[str] = None, since: Optional[NewType.<locals>.new_type] = None, search_query: Optional[str] = None, include_all_networks: Optional[bool] = None, third_party_instance_id: Optional[str] = None) → mautrix.client.api.types.misc.RoomDirectoryResponse[source]

Get a list of public rooms from the server’s room directory.

See also: API reference

Parameters:
  • limit (Optional[int]) – The maximum number of results to return.
  • server (Optional[str]) – The server to fetch the room directory from. Defaults to the user’s server.
  • since (Optional[DirectoryPaginationToken[str]]) – A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag.
  • search_query (Optional[str]) – A string to search for in the room metadata, e.g. name, topic, canonical alias etc.
  • include_all_networks (Optional[bool]) – Whether or not to include rooms from all known networks/protocols from application services on the homeserver. Defaults to false.
  • third_party_instance_id (Optional[str]) – The specific third party network/protocol to request from the homeserver. Can only be used if include_all_networks is false.
Return type:

RoomDirectoryResponse
Returns:

The relevant pagination tokens, an estimate of the total number of public rooms and the paginated chunk of public rooms.
get_room_directory_visibility(room_id: NewType.<locals>.new_type) → mautrix.client.api.types.misc.RoomDirectoryVisibility[source]

Get the visibility of the room on the server’s public room directory.

See also: API reference

Parameters:room_id (RoomID[str]) – The ID of the room.
Return type:RoomDirectoryVisibility
Returns:The visibility of the room in the directory.
invite_user(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type) → None[source]

Invite a user to participate in a particular room. They do not start participating in the room until they actually join the room.

Only users currently in the room can invite other users to join that room.

If the user was invited to the room, the homeserver will add a m.room.member event to the room.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room to which to invite the user.
  • user_id (UserID[str]) – The fully qualified user ID of the invitee.
Return type:

None
join_room(room_id_or_alias: Union[NewType.<locals>.new_type, NewType.<locals>.new_type], servers: List[str] = None, third_party_signed: NewType.<locals>.new_type = None, max_retries: int = 4) → NewType.<locals>.new_type[source]

Start participating in a room, i.e. join it by its ID or alias, with an optional list of servers to ask about the ID from.

See also: API reference

Parameters:
  • room_id_or_alias (Union[RoomID[str], RoomAlias[str]]) – The ID of the room to join, or an alias pointing to the room.
  • servers (Optional[List[str]]) – A list of servers to ask about the room ID to join. Not applicable for aliases, as aliases already contain the necessary server information.
  • third_party_signed (Optional[JSON[Union[str, int, float, None, Dict[str, _Forwardref], List[_Forwardref]]]]) – A signature of an m.third_party_invite token to prove that this user owns a third party identity which has been invited to the room.
  • max_retries (int) – The maximum number of retries. Used to circumvent a Synapse bug with accepting invites over federation. 0 means only one join call will be attempted. See: matrix-org/synapse#2807
Return type:

RoomID[str]
Returns:

The ID of the room the user joined.
join_room_by_id(room_id: NewType.<locals>.new_type, third_party_signed: NewType.<locals>.new_type = None) → NewType.<locals>.new_type[source]

Start participating in a room, i.e. join it by its ID.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room to join.
  • third_party_signed (Optional[JSON[Union[str, int, float, None, Dict[str, _Forwardref], List[_Forwardref]]]]) – A signature of an m.third_party_invite token to prove that this user owns a third party identity which has been invited to the room.
Return type:

RoomID[str]
Returns:

The ID of the room the user joined.
kick_user(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type, reason: Optional[str] = '') → None[source]

Kick a user from the room.

The caller must have the required power level in order to perform this operation.

Kicking a user adjusts the target member’s membership state to be leave with an optional reason. Like with other membership changes, a user can directly adjust the target member’s state by calling EventMethods.send_state_event() with EventTypes.ROOM_MEMBER as the event type and the user_id as the state key.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room from which the user should be kicked.
  • user_id (UserID[str]) – The fully qualified user ID of the user being kicked.
  • reason (Optional[str]) – The reason the user has been kicked. This will be supplied as the reason on the target’s updated m.room.member event.
Return type:

None
leave_room(room_id: NewType.<locals>.new_type) → None[source]

Stop participating in a particular room, i.e. leave the room.

If the user was already in the room, they will no longer be able to see new events in the room. If the room requires an invite to join, they will need to be re-invited before they can re-join.

If the user was invited to the room, but had not joined, this call serves to reject the invite.

The user will still be allowed to retrieve history from the room which they were previously allowed to see.

See also: API reference

Parameters:room_id (RoomID[str]) – The ID of the room to leave.
Return type:None
remove_room_alias(alias_localpart: str) → None[source]

Remove a mapping of room alias to room ID.

Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or server administrator.

See also: API reference

Parameters:alias_localpart (str) – The room alias to remove.
Return type:None
set_room_directory_visibility(room_id: NewType.<locals>.new_type, visibility: mautrix.client.api.types.misc.RoomDirectoryVisibility) → None[source]

Set the visibility of the room in the server’s public room directory.

Servers may choose to implement additional access control checks here, for instance that room visibility can only be changed by the room creator or a server administrator.

Parameters:
  • room_id (RoomID[str]) – The ID of the room.
  • visibility (RoomDirectoryVisibility) – The new visibility setting for the room.
Return type:None
unban_user(room_id: NewType.<locals>.new_type, user_id: NewType.<locals>.new_type) → None[source]

Unban a user from the room. This allows them to be invited to the room, and join if they would otherwise be allowed to join according to its join rules. The caller must have the required power level in order to perform this operation.

See also: API reference

Parameters:
  • room_id (RoomID[str]) – The ID of the room from which the user should be unbanned.
  • user_id (UserID[str]) – The fully qualified user ID of the user being banned.
Return type:

None

mautrix.client.api.user_data module

class mautrix.client.api.user_data.UserDataMethods(mxid: NewType.<locals>.new_type, api: mautrix.api.http.HTTPAPI = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, *args, **kwargs)[source]

Bases: mautrix.client.api.base.BaseClientAPI

Methods in section 10 User Data of the spec. These methods are used for setting and getting user metadata and searching for users.

See also: API reference

get_avatar_url(user_id: str) → str[source]

Get the avatar URL of a user.

See also: API reference

Parameters:user_id (str) – The ID of the user whose avatar to get.
Returns://`` URI to the user’s avatar.
Return type:The ``mxc
get_displayname(user_id: str) → str[source]

Get the display name of a user.

See also: API reference

Parameters:user_id (str) – The ID of the user whose display name to get.
Return type:str
Returns:The display name of the given user.
get_profile(user_id: str) → mautrix.client.api.types.users.Member[source]

Get the combined profile information for a user.

See also: API reference

Parameters:user_id (str) – The ID of the user whose profile to get.
Return type:Member
Returns:The profile information of the given user.
search_users(search_query: str, limit: Optional[int] = 10) → mautrix.client.api.types.users.UserSearchResults[source]

Performs a search for users on the homeserver. The homeserver may determine which subset of users are searched, however the homeserver MUST at a minimum consider the users the requesting user shares a room with and those who reside in public rooms (known to the homeserver). The search MUST consider local users to the homeserver, and SHOULD query remote users as part of the search.

The search is performed case-insensitively on user IDs and display names preferably using a collation determined based upon the Accept-Language header provided in the request, if present.

See also: API reference

Parameters:
  • search_query (str) – The query to search for.
  • limit (Optional[int]) – The maximum number of results to return.
Return type:

UserSearchResults
Returns:

The results of the search and whether or not the results were limited.
set_avatar_url(avatar_url: str) → None[source]

Set the avatar of the current user.

See also: API reference

Parameters:avatar_url (str) – The mxc:// URI to the new avatar.
Return type:None
set_displayname(displayname: str) → None[source]

Set the display name of the current user.

See also: API reference

Parameters:displayname (str) – The new display name for the user.
Return type:None

Module contents