Caution
17/08/2026 - While the library is still in development. Grave changes to the API should not be a concern any longer.
A client-side Java library for the Matrix protocol.
This library aims to allow authors to build any kind of Matrix program such as a bot or a desktop client, the library handles all matters of serialization, validation and authentication.
| Service | Capabilities | Status |
|---|---|---|
| Rooms | Banning, kicking, room summary, room search | Supported |
| Events | Sending and reading events, /sync |
Mostly supported |
| User Data | Profile search, profile modification | Supported |
| Filtering | Creating and retrieving filters | Supported |
| Auth | OpenIDConnect handshake | Partial |
| Capability Awareness | Notify consumers about user capabilities | Not yet implemented |
The baseline to reach v1.0 is to implement all endpoints that are required in the specification, this means:
- Support for OAuth 2.0 and Legacy API Auth (not all flows will be delivered in 1.0).
- Be able to send and receive events seamlessly without handling raw JSON. (Done, except for
/syncwho allows it) - Get room and server information without losing any data field while deserializing. (Done)
- This project does not handle multimedia resources, it does expose the necessary Objects to handle serialization (RoomMessage) but consumers are required to bring their own library to pass required metadata.
- This project does not allow for the creation or hookup of custom event types, for setUpClientPrints:
org.custom.type. It does recognize these events withUnknownEvent.javabut consumers will be required to cast to a proper Object type. - Resource serialization/deserialization depends heavily on Jackson 3.0.
- There is a limit of tolerance to wrongly created events, but in general the library will not attempt to serialize badly created objects. See: matrix-org/matrix-spec-proposals#2801 on why this is the case.
Currently, the only way to use this library is to compile it on your own using mvn compile.
Set-up and usage is described in the examples module.
- Java 25+
- Tests use WireMock for HTTP stubbing and JUnit 5 as the test framework.
- Each service component has its own test file; all tests must pass to ensure the library works as intended.
To run the test suite:
./mvnw testNote
When using IntelliJ, JUnit might throw IllegalAccessError,
fix this by either checking "Do not use --module-path option" or configuring Maven as the
test runner.
- Jackson required for JSON handling.
- java-http required for creating a small server for callbacks.
- Jspecify allows handling null values with ease.
- SLF4J required for logging.
See LICENSE