platforms.matrix module

Matrix platform adapter using matrix-nio.

Wraps the matrix-nio AsyncClient and converts Matrix events into IncomingMessage instances for the shared MessageProcessor.

async platforms.matrix.download_matrix_media(client, event)

Download (and optionally decrypt) a media attachment from Matrix.

Return type:

tuple[bytes, str, str]

Parameters:

• client (AsyncClient)

• event (RoomMessageMedia | RoomEncryptedMedia)

async platforms.matrix.save_matrix_credentials(credentials_file, homeserver, client)

Persist Matrix login credentials (preserving extra keys like seeds).

Return type:

None

Parameters:

• credentials_file (str)

• homeserver (str)

• client (nio.AsyncClient)

async platforms.matrix.load_matrix_credentials(credentials_file)

Load previously saved Matrix credentials, or return None.

Return type:

dict | None

Parameters:

credentials_file (str)

platforms.matrix.trust_all_devices(client)

Mark every known device of every tracked user as trusted.

Return type:

None

Parameters:

client (nio.AsyncClient)

async platforms.matrix.setup_cross_signing(client, password, credentials_file, saved_seeds=None)

Generate cross-signing keys, upload them, and self-sign the device.

If saved_seeds is provided the keys are re-derived from persisted seeds instead of generating new ones. Seeds are persisted to credentials_file for future restarts.

Return type:

None

Parameters:

• client (nio.AsyncClient)

• password (str)

• credentials_file (str)

• saved_seeds (dict[str, str] | None)

class platforms.matrix.MatrixPlatform(message_handler, *, homeserver, user_id, password='', store_path='nio_store', credentials_file='matrix_credentials.json', media_cache=None, config=None)

Bases: PlatformAdapter

Platform adapter for Matrix via matrix-nio.

Parameters:

• message_handler (Callable[[IncomingMessage, PlatformAdapter], Awaitable[None]]) – Async callback that receives IncomingMessage instances.

• homeserver (str) – Matrix homeserver URL.

• user_id (str) – Matrix user ID for the bot.

• password (str) – Password (only needed for first login).

• store_path (str) – Path to the nio E2EE key store.

• credentials_file (str) – Path to the JSON file for persisting login credentials.

• media_cache (MediaCache | None)

• config (Config | None)

__init__(message_handler, *, homeserver, user_id, password='', store_path='nio_store', credentials_file='matrix_credentials.json', media_cache=None, config=None)

Initialize the instance.

Parameters:

• message_handler (Callable[[IncomingMessage, PlatformAdapter], Awaitable[None]]) – The message handler value.

• homeserver (str)

• user_id (str)

• password (str)

• store_path (str)

• credentials_file (str)

• media_cache (MediaCache | None)

• config (Config | None)

Return type:

None

property name: str

Name.

Returns:

Result string.

Return type:

str

property is_running: bool

Check whether is running.

Returns:

True on success, False otherwise.

Return type:

bool

property bot_identity: dict[str, str]

Return the bot’s own identity on this platform.

Returns a dict with at minimum platform and user_id. Adapters should override to provide display_name and mention where available. The default returns an empty user_id (safe to call before login completes).

async start()

Start.

Return type:

None

async stop()

Stop.

Return type:

None

async send(channel_id, text)

Send.

Parameters:

• channel_id (str) – Discord/Matrix channel identifier.

• text (str) – Text content.

Returns:

Result string.

Return type:

str

async send_file(channel_id, data, filename, mimetype='application/octet-stream')

Send file.

Parameters:

• channel_id (str) – Discord/Matrix channel identifier.

• data (bytes) – Input data payload.

• filename (str) – The filename value.

• mimetype (str) – The mimetype value.

Returns:

The mxc:// content URI, or None on failure.

Return type:

str | None

async start_typing(channel_id)

Start typing.

Parameters:

channel_id (str) – Discord/Matrix channel identifier.

Return type:

None

async stop_typing(channel_id)

Stop typing.

Parameters:

channel_id (str) – Discord/Matrix channel identifier.

Return type:

None

async list_servers_and_channels()

Return all Matrix rooms the bot is in.

Matrix doesn’t have a guild/server hierarchy in the same way Discord does — each room is listed as a standalone entry.

Return type:

list[dict[str, Any]]

async fetch_history(channel_id, limit=100)

Fetch history.

Parameters:

• channel_id (str) – Discord/Matrix channel identifier.

• limit (int) – Maximum number of items.

Returns:

The result.

Return type:

list[HistoricalMessage]