Matrix Python SDK

The SDK provides two distinct layers of interaction:

1. API Layer (matrix_client.api): A low-level layer that wraps raw HTTP API calls. It has minimal business logic. You can provide an access token for requests and a custom txn_id (transaction ID) which the SDK will increment for each request.
2. Client Layer (matrix_client.client): A high-level layer that wraps the API layer. It provides a rich object model (such as Room objects) to perform actions more easily.

Choose the API layer if you need direct access to raw HTTP calls, and the Client layer if you want to work with high-level abstractions and object models.

You can install the SDK via the stable PyPI release or by installing the development version from source.

Stable release

Install using pip. This will automatically install all necessary dependencies.

Development version

Clone the repository and install using setup.py from the root directory.

Note: The maintainers strongly recommend using the matrix-nio library instead of this SDK, as it is more featureful and actively maintained.

# Stable release
pip install matrix_client

# Development version
git clone https://github.com/matrix-org/matrix-python-sdk.git
cd matrix-python-sdk
python setup.py install

The repository includes a collection of Python 3 samples. You can run them by setting the PYTHONPATH to the current directory to ensure imports resolve correctly.

PYTHONPATH=. python samples/samplename.py

The MatrixHttpApi class allows you to make direct HTTP API calls to a Matrix homeserver using an access token.

from matrix_client.api import MatrixHttpApi

matrix = MatrixHttpApi("https://matrix.org", token="some_token")
response = matrix.send_message("!roomid:matrix.org", "Hello!")

The MatrixClient class provides an object-oriented way to interact with a Matrix homeserver. It supports user registration, logging in, creating rooms, and sending messages through room objects.

from matrix_client.client import MatrixClient

client = MatrixClient("http://localhost:8008")

# New user registration
token = client.register_with_password(username="foobar", password="monkey")

# Existing user login
token = client.login(username="foobar", password="monkey")

# Room interaction
room = client.create_room("my_room_alias")
room.send_text("Hello!")

To continuously receive events without blocking your main thread, use start_listener_thread.

• start_listener_thread(timeout_ms=30000, exception_handler=None): Starts a daemon thread that runs listen_forever.
• listen_forever(timeout_ms=30000, exception_handler=None, bad_sync_timeout=5): A blocking loop that polls the server. Use this if you want to run the sync loop in your main thread.
• stop_listener_thread(): Stops the background thread.

If an exception_handler is provided, it will be called when errors occur during sync.

def handle_error(e):
    print(f"Error occurred: {e}")

client.start_listener_thread(timeout_ms=10000, exception_handler=handle_error)

# ... do other work ...

client.stop_listener_thread()

Use upload(content, content_type, filename=None) to upload bytes to the homeserver. It returns a MXC URL (e.g., mxc://homeserver.com/media/abc...).

with open("image.png", "rb") as f:
    mxc_url = client.upload(f.read(), "image/png", filename="image.png")
print(f"Uploaded to: {mxc_url}")

Use the login method to authenticate with a username and password. This method returns the access token and automatically initiates a /sync request to populate the client state if sync=True (default).

Parameters

• username (str): Account username.
• password (str): Account password.
• limit (int): Number of messages to return when syncing (deprecated, use sync filters).
• sync (bool): Whether to initiate a /sync request after logging in.
• device_id (str, optional): ID of the client device. If not specified, the server auto-generates one.

client = MatrixClient("https://matrix.org")
token = client.login(username="myuser", password="mypassword")

Use the following methods to manage room membership:

• create_room(alias=None, is_public=False, invitees=None): Creates a new room. Returns a Room object.
• join_room(room_id_or_alias): Joins an existing room via its ID or alias. Returns a Room object.

# Create a room
new_room = client.create_room(alias="#myroom:matrix.org", is_public=True)

# Join a room
room = client.join_room("#existing:matrix.org")

If the homeserver has guest registration enabled, you can register a guest account using register_as_guest(). This returns the access token.

client = MatrixClient("https://matrix.org")
token = client.register_as_guest()