matrixlib.client module

General Matrix client functionality

class matrixlib.client.Client(storage: Storage, callbacks: dict = {}, base_client_url: str | None = None, well_known: dict[str, Any] | None = None, versions: dict[str, Any] | None = None)

Represents a client connection



The storage object to use


Functions that will be called to perform processing needed by the client


The base URL to use to connect to the server, including the _matrix/client/ suffix. If omitted, the client must have previously logged in and stored the base URL in the storage


The contents of the .well-known file obtained from server discovery.


The result of calling /_matrix/client/versions on the server, for example as returned by the discover function.

async authenticated(req_func, *args, **kwargs) ClientResponse

Make an authenticated request to the homeserver.



the function to call to make the request. e.g. to make an authenticated GET request, this would be self.http_session.get.

*args, **kwargs:

the arguments to pass to req_func.

async claim_otks(algorithm: str, devices: dict[str, list[str]], timeout: int | None = None) Tuple[dict[str, dict[str, Tuple[str, Any]]], list[str]]

Claim one-time keys for the given devices.



the key algorithm for the one-time keys that we want to request


the devices that we want to request one-time keys for. This is given as a dict, mapping user IDs to a list of device IDs


how long to wait, in milliseconds, for a response from remote servers

Returns a tuple consisting of:

  • a dict mapping user IDs to device IDs to (key ID, one-time key) tuple. A requested device may be missing, indicating that no one-time key for that device could be obtained

  • a list of remote servers that failed to respond in time

async close() None

Free up resources used by the client.

property device_id: str | None

The device ID of the logged-in user, or None if not logged in

async log_in_with_password(identifier: str | dict[str, Any], password: str, identifier_type: str = 'user', **kwargs: dict[str, Any]) dict[str, Any]

Log in to the server



the identifier to use. The format depends on the identifier type, but in most cases will be a string.


the password to use.


the type of identifer to use. The default, 'user' indicates that the identifier is a username or user ID. Other recognized values are 'email' and 'phone'. Any other values will be passed unchanged to the login endpoint. For 'phone', identifier is either a dict with country (the two-letter country code that the phone number is from) and phone (the actual phone number) properties, or a the canonicalised phone number as a string. For unknown values, the identifier should be a dict.

async log_out() None

Log out the current session and clear out the storage.

async login_methods() list[str]

Get a list of the login methods supported by the server.

make_txn_id() str

Generate a unique transaction ID

async re_log_in(auth_parameter: str | dict[str, Any], login_type: str = 'password') None

Re-log in after getting soft logged out



The authentication parameter (e.g. password or token) to use.


The method of logging in. The default value, 'password', indicates that you are logging in with a password. A value of 'token' indicates that you are logging in with a token. An unknown value will set that as the type in the request body, and auth_parameter must be a dict whose contents will be copied to the request body.

async send_event(room_id: str, event_type: str, event_content: dict[str, Any], retry_ms: int = 0, txn_id: str | None = None) Tuple[str, str]

Send an event to a room



the ID of the room to send to


the type of event to send


the content of the event


how long to retry sending, in milliseconds


the transaction ID to use. If none is specified, one is generated.

async send_to_device(event_type: str, event_contents: dict[str, dict[str, dict]], retry_ms: int = 0, txn_id: str | None = None) None

Send an events to devices



the ID of the room to send to


the type of event to send


a map from user ID to device ID to event content. If “*” is used as the device ID, the event is sent to all of the user’s devices.


how long to retry sending, in milliseconds


Start the sync loop


Stop the sync loop

url(endpoint: str) str

Returns the full URL of a given endpoint

property user_id: str | None

The user ID of the logged-in user, or None if not logged in

class matrixlib.client.ClientClosed

A message indicating that the client is closed

class matrixlib.client.DeviceChanges(changed: list[str], left: list[str])

A message indicating that user’s devices have changed

Create new instance of DeviceChanges(changed, left)

changed: list[str]

Users whose devices have changed

left: list[str]

Users who no longer share a room

class matrixlib.client.LeftRoom(room_id: str)

A message indicating that the user has left a room

Create new instance of LeftRoom(room_id,)

room_id: str

The ID of the room that the user left

class matrixlib.client.OneTimeKeysCount(otk_count: dict[str, int], has_to_device: bool)

A message indicating the one-time keys count from the sync

Create new instance of OneTimeKeysCount(otk_count, has_to_device)

has_to_device: bool

Whether any to-device messages were in the sync

otk_count: dict[str, int]

Dict mapping algorithm name to one-time keys count

class matrixlib.client.RoomStateUpdates(room_id: str, events: list[])

A message giving state updates for a room from sync

Create new instance of RoomStateUpdates(room_id, events)

static create_from_sync(room_id: str, state_updates: dict) RoomStateUpdates
events: list[]

The state events

room_id: str

The room ID

class matrixlib.client.RoomTimelineUpdates(room_id: str, events: list[], limited: bool, prev_batch: str | None)

A message giving timeline for a room from sync

Create new instance of RoomTimelineUpdates(room_id, events, limited, prev_batch)

static create_from_sync(room_id: str, timeline_updates: dict) RoomTimelineUpdates
events: list[]

The state events

limited: bool

Whether the timeline update was limited

prev_batch: str | None

The token to retrieve previous messages

room_id: str

The room ID

class matrixlib.client.Storage(*args, **kwargs)

Protocol for classes that persist data for the client

clear() None
get(key: str, default: Any = None) Any
class matrixlib.client.SyncFailed(delay: int)

A message indicating that a sync call has failed

Create new instance of SyncFailed(delay,)

delay: int

The amount of time that the loop will wait before retrying

class matrixlib.client.SyncResumed

A message indicating that the sync loop has resumed after a previous failure

class matrixlib.client.ToDeviceEvents(events: list[])

A message indicating that to-device events have been received

Create new instance of ToDeviceEvents(events,)

events: list[]

The to-device events

async matrixlib.client.check_response(resp: ClientResponse) tuple[int, dict[str, Any]]

Checks whether an HTTP response is an error.

If successful, returns the HTTP code and the response body. Raises an exception on error.

async str) tuple[str, dict, dict] | None

Perform discovery on the given server name.

On success, returns a tuple consisting of homeserver’s base client-server URL (the homeserver’s base URL with _matrix/client appended), the full contents of the JSON object returned from the .well-known file, and the full contents of the server’s /_matrix/client/versions response. On failure, returns None.

async matrixlib.client.retry(limit: int, req_func, *args, **kwargs) ClientResponse

Retry a request until a time limit is reached.

The request will be retried if a non-Matrix response is received, or if the request was rate limited.

Note that this will not apply a timeout to the actual request: if the server responds slowly, then it may exceed the retry time limit. To limit the time taken by the request, a timeout argument should be passed to the request function.



the time limit, in milliseconds


the function to call to make the request. e.g. to make a GET request, this could be session.get, where session is an aiohttp.ClientSession.

*args, **kwargs:

the arguments to pass to req_func.