Matrix Client SDK

0.4.0 · active · verified Thu Apr 16

The `matrix-client` library is a Client-Server SDK for the Matrix protocol, providing functionality to interact with Matrix homeservers. It is currently at version 0.4.0 and releases are infrequent, often addressing breaking changes or incompatibilities with the Matrix protocol or Synapse homeserver.

Common errors

```
matrix_client.client.MatrixRequestError: 403 Forbidden: Invalid homeserver or credentials.
```
cause This error often occurs when `matrix-client` prior to v0.4.0 attempts to connect to Synapse homeservers v1.38.0+ due to changes in authorization header handling, or simply incorrect login credentials.

fix Upgrade to `matrix-client` v0.4.0 and initialize `MatrixClient(homeserver_url, use_authorization_header=True)`. Double-check your username and password.
```
ModuleNotFoundError: No module named 'olm'
```
cause You are attempting to use experimental End-to-End Encryption (E2E) features, but the necessary native `libolm` library and/or its Python wrapper have not been installed.

fix First, install `libolm` (version 3.0.0 or higher) system-wide on your operating system. Then, install the Python E2E dependencies: `pip install matrix-client[e2e]`.
```
AttributeError: 'Room' object has no attribute 'get_name'
```
cause You are using a deprecated getter method (e.g., `get_name()`) that was removed or replaced by direct attribute access.

fix Access the attribute directly (e.g., `room.name`) instead of using `room.get_name()`. Consult the library's documentation for current API methods.

Warnings

breaking Older versions of `matrix-client` (prior to 0.4.0) are incompatible with Synapse homeservers running version 1.38.0 or newer, leading to connection issues or failed API calls.
Fix: Upgrade to `matrix-client` v0.4.0 or newer. When initializing `MatrixClient`, it's recommended to set `use_authorization_header=True` for better compatibility with modern Synapse versions.
gotcha End-to-end encryption (E2E) support is experimental, disabled by default, and requires specific native `libolm` (v3.0.0+) and Python dependencies (`matrix-client[e2e]`) to be installed.
Fix: First, install `libolm` (version 3.0.0 or higher) system-wide on your operating system. Then, install the Python E2E dependencies using `pip install matrix-client[e2e]`.
deprecated Many getter and setter methods (e.g., `get_name()`, `set_topic()`) were deprecated in v0.3.2 in favor of direct attribute access or alternative methods.
Fix: Refer to the latest documentation for preferred ways to access and modify properties (e.g., `room.name` instead of `room.get_name()`), avoiding deprecated methods.
deprecated The Matrix API endpoints `/initialSync` and `/events` were deprecated in v0.0.4, with `/sync` becoming the standard for event retrieval.
Fix: Ensure your code uses the `/sync` API calls via the client's methods, rather than making direct calls to the deprecated endpoints, which may no longer be supported by homeservers.

Install

pip install matrix-client Standard Install
pip install matrix-client[e2e] Install with E2E Encryption Support

Imports

MatrixClient

from matrix_client.client import MatrixClient

Room
```
from matrix_client.room import Room
```
Typically accessed via MatrixClient methods, not directly instantiated.

Quickstart

This quickstart demonstrates how to log into a Matrix homeserver, join a room, send a message, and then log out. Ensure `MATRIX_HOMESERVER_URL`, `MATRIX_USERNAME`, `MATRIX_PASSWORD`, and `MATRIX_ROOM` environment variables are set or replaced with actual values.

import os
from matrix_client.client import MatrixClient

HOMESERVER_URL = os.environ.get('MATRIX_HOMESERVER_URL', 'https://matrix.org')
USERNAME = os.environ.get('MATRIX_USERNAME', 'test_user')
PASSWORD = os.environ.get('MATRIX_PASSWORD', 'test_password')
ROOM_ID_OR_ALIAS = os.environ.get('MATRIX_ROOM', '#test:matrix.org') # Replace with a valid room

try:
    # For matrix-client v0.4.0+, `use_authorization_header=True` is recommended
    # for better compatibility with modern Synapse versions.
    client = MatrixClient(HOMESERVER_URL, use_authorization_header=True)
    client.login(username=USERNAME, password=PASSWORD)
    print(f"Successfully logged in as {USERNAME}")

    # Try to join a room
    room = client.join_room(ROOM_ID_OR_ALIAS)
    print(f"Successfully joined room: {room.name} ({room.room_id})")

    # Send a message
    room.send_text("Hello from matrix-client Python SDK!")
    print("Sent a test message.")

    # Logout
    client.logout()
    print("Logged out.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure MATRIX_HOMESERVER_URL, MATRIX_USERNAME, MATRIX_PASSWORD, and MATRIX_ROOM are set correctly and are valid.")

view raw JSON →