20 releases (11 breaking)

0.11.0 Feb 1, 2023
0.10.0 Sep 12, 2022
0.9.0 Apr 28, 2022
0.8.0 Feb 19, 2022
0.0.0 Jan 5, 2017

#339 in Web programming

Download history 61/week @ 2023-02-12 117/week @ 2023-02-19 12/week @ 2023-02-26 80/week @ 2023-03-05 98/week @ 2023-03-12 76/week @ 2023-03-19 26/week @ 2023-03-26 29/week @ 2023-04-02 36/week @ 2023-04-09 34/week @ 2023-04-16 15/week @ 2023-04-23 85/week @ 2023-04-30 60/week @ 2023-05-07 26/week @ 2023-05-14 20/week @ 2023-05-21 81/week @ 2023-05-28

190 downloads per month
Used in 5 crates (3 directly)

MIT license

23K SLoC


crates.io page docs.rs page license: MIT

ruma-client is a low-level Matrix client library for Rust.


This project is a work in progress and not ready for production usage yet. If you are looking to build a client application or a bot, you are likely going to have a better time using the Matrix Rust SDK, which also builds on the other Ruma crates but provides a higher-level API.


A minimal Matrix client library.


Begin by creating a Client, selecting one of the type aliases from ruma_client::http_client for the generic parameter. For the client API, there are login and registration methods provided for the client (feature client-api):

# // HACK: "ignore" the doctest here because client.log_in needs client-api feature.
// type HttpClient = ruma_client::http_client::_;
# type HttpClient = ruma_client::http_client::Dummy;
# let work = async {
let homeserver_url = "https://example.com".parse().unwrap();
let client = ruma::Client::builder()

let session = client
    .log_in("@alice:example.com", "secret", None, None)

// You're now logged in! Write the session to a file if you want to restore it later.
// Then start using the API!
# Result::<(), ruma_client::Error<_, _>>::Ok(())
# };

You can also pass an existing access token to the Client constructor to restore a previous session rather than calling log_in. This can also be used to create a session for an application service that does not need to log in, but uses the access_token directly:

# type HttpClient = ruma_client::http_client::Dummy;
# async {
let homeserver_url = "https://example.com".parse().unwrap();
let client = ruma_client::Client::builder()

// make calls to the API
# Result::<(), ruma_client::Error<_, _>>::Ok(())
# };

The Client type also provides methods for registering a new account if you don't already have one with the given homeserver.

Beyond these basic convenience methods, ruma-client gives you access to the entire Matrix client-server API via the request method. You can pass it any of the Request types found in ruma::api::* and get back a corresponding response from the homeserver.

For example:

# let homeserver_url = "https://example.com".parse().unwrap();
# async {
# let client = ruma_client::Client::builder()
#     .homeserver_url(homeserver_url)
#     .build::<ruma_client::http_client::Dummy>()
#     .await?;

use ruma_client_api::alias::get_alias;
use ruma_common::{api::MatrixVersion, room_alias_id, room_id};

let response = client

assert_eq!(response.room_id, room_id!("!n8f893n9:example.com"));
# Result::<(), ruma_client::Error<_, _>>::Ok(())
# };

Crate features

The following features activate http client types in the [http_client] module:

  • hyper
  • hyper-native-tls
  • hyper-rustls
  • isahc
  • reqwest – if you use the reqwest library already, activate this feature and configure the TLS backend on reqwest directly. If you want to use reqwest but don't depend on it already, use one of the sub-features instead. For details on the meaning of these, see reqwest's documentation:
    • reqwest-native-tls
    • reqwest-native-tls-alpn
    • reqwest-native-tls-vendored
    • reqwest-rustls-manual-roots
    • reqwest-rustls-webpki-roots
    • reqwest-rustls-native-roots


~419K SLoC