A high-level, batteries-included Matrix client library written in Rust.

This crate seeks to be a general-purpose library for writing software using the Matrix Client-Server API to communicate with a Matrix homeserver. If you're writing a typical Matrix client or bot, this is likely the crate you need.

However, the crate is designed in a modular way and depends on several other lower-level crates. If you're attempting something more custom, you might be interested in these:

Getting started

The central component you'll be interacting with is the [Client]. A basic use case will include instantiating the client, logging in as a user, registering some event handlers and then syncing.

This is demonstrated in the example below.

```rust,norun use matrixsdk::{ Client, config::SyncSettings, ruma::{user_id, events::room::message::SyncRoomMessageEvent}, };

[tokio::main]

async fn main() -> anyhow::Result<()> { let alice = userid!("@alice:example.org"); let client = Client::builder().userid(alice).build().await?;

// First we need to log in.
client.login_username(alice, "password").send().await?;

client.add_event_handler(|ev: SyncRoomMessageEvent| async move {
    println!("Received a message {:?}", ev);
});

// Syncing is important to synchronize the client state with the server.
// This method will never return.
client.sync(SyncSettings::default()).await;

Ok(())

} ```

More examples can be found in the [examples] directory.

Crate Feature Flags

The following crate feature flags are available:

| Feature | Default | Description | | ------------------- | :-----: | -------------------------------------------------------------------------------------------------------------------------- | | anyhow | No | Better logging for event handlers that return anyhow::Result | | e2e-encryption | Yes | End-to-end encryption (E2EE) support | | eyre | No | Better logging for event handlers that return eyre::Result | | image-proc | No | Image processing for generating thumbnails | | image-rayon | No | Enables faster image processing | | js | No | Enables JavaScript API usage for things like the current system time on WASM (does nothing on other targets) | | markdown | No | Support for sending Markdown-formatted messages | | qrcode | Yes | QR code verification support | | sled | Yes | Persistent storage of state and E2EE data (optionally, if feature e2e-encryption is enabled), via Sled | | indexeddb | No | Persistent storage of state and E2EE data (optionally, if feature e2e-encryption is enabled) for browsers, via IndexedDB | | socks | No | SOCKS support in the default HTTP client, [reqwest] | | sso-login | No | Support for SSO login with a local HTTP server |

Enabling logging

Users of the matrix-sdk crate can enable log output by depending on the tracing-subscriber crate and including the following line in their application (e.g. at the start of main):

rust tracing_subscriber::fmt::init();

The log output is controlled via the RUST_LOG environment variable by setting it to one of the error, warn, info, debug or trace levels. The output is printed to stdout.

The RUST_LOG variable also supports a more advanced syntax for filtering log output more precisely, for instance with crate-level granularity. For more information on this, check out the [tracing_subscriber documentation].