The Matrix SDK for Android wraps the Matrix REST API calls in asynchronous Java methods and provides basic structures for storing and handling data.
It is an Android Studio (gradle) project containing two modules:
- sdk - The SDK
- app - The sample app using the SDK
The Matrix APIs are split into several categories (see matrix api). Basic usage is:
- Log in or register to a home server -> get the user's credentials
- Start a session with the credentials
- Start listening to the event stream
- Make matrix API calls
Bugs / Feature Requests
Think you've found a bug? Want a new feature on the client? Please open an issue on JIRA:
- Create an account and login to https://matrix.org/jira
- Navigate to the
- Click Create Issue - Please be as descriptive as possible, with reproduction steps if possible.
All issues in JIRA are public.
Want to fix a bug or add a new feature? Check JIRA first to see if someone else is
handling this issue. If no one is actively working on the issue, then please fork
develop branch when writing your fix, and open a pull request when you're
ready. Do not base your pull requests off
To log in, use an instance of the login API client.
new LoginApiClient("https://matrix.org").loginWithPassword("user", "password", callback);
If successful, the callback will provide the user credentials to use from then on.
Starting the matrix session
The session represents one user's session with a particular home server. There can potentially be multiple sessions for handling multiple accounts.
MXSession session = new MXSession(credentials);
sets up a session for interacting with the home server.
The session gives access to the different APIs through the REST clients:
session.getEventsRestClient() for the events API
session.getProfileRestClient() for the profile API
session.getPresenceRestClient() for the presence API
session.getRoomsRestClient() for the rooms API
For the complete list of methods, please refer to the [Javadoc].
Example Getting the list of members of a chat room would look something like this:
The same session object should be used for each request. This may require use
of a singleton, see the
Matrix singleton in the
app module for an
The event stream
One important part of any Matrix-enabled app will be listening to the event stream, the live flow of events (messages, state changes, etc.). This is done by using:
This starts the events thread and sets it to send events to a default listener.
It may be useful to use this in conjunction with an Android
control whether the event stream is running in the background or not.
The data handler
The data handler provides a layer to help manage data from the events stream. While it is possible to write an app with no data handler and manually make API calls, using one is highly recommended for most uses. The data handler :
- Handles events from the events stream
- Stores the data in its storage layer
- Provides the means for an app to get callbacks for events
- Provides and maintains room objects for room-specific operations (getting messages, joining, kicking, inviting, etc.)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
creates a data handler with the default in-memory storage implementation.
Setting up the session
MXSession session = new MXSession(credentials, dataHandler);
Starting the event stream
Registering a listener
To be informed of events, the app needs to implement an event listener.
This listener should subclass
MXEventListener and override the methods as needed:
Triggered when a user's presence has been updated.
Triggered when a live event has come down the event stream.
Triggered when an old event (from history), or back event, has been returned after a request for more history.
Triggered when the initial sync process has completed. The initial sync is the first call the event stream makes
to initialize the state of all known rooms, users, etc.
The Room object
The Room object provides methods to interact with a room (getting message history, joining, etc).
Room room = session.getDataHandler().getRoom(roomId);
gets (or creates) the room object associated with the given room ID.
The RoomState object represents the room's state at a certain point in time: its name, topic, visibility (public/private), members, etc. onLiveEvent and onBackEvent callbacks (see Registering a listener) return the event, but also the state of the room at the time of the event to serve as context for building the display (e.g. the user's display name at the time of their message). The state provided is the one before processing the event, if the event happens to change the state of the room.
When entering a room, an app usually wants to display the last messages. This is done by calling
The events are then returned through the
onBackEvent(event, roomState) callback in reverse order (most recent first).
This does not trigger all of the room's history to be returned but only about 15 messages. Calling
requestHistory() again will then
retrieve the next (earlier) 15 or so, and so on. To start requesting history from the current live state (e.g. when opening or reopening a room),
must be called prior to the history requests.
The content manager
Matrix home servers provide a content API for the downloading and uploading of content (images, videos, files, etc.). The content manager provides the wrapper around that API.
retrieves the content manager associated with the given session.
Content hosted by a home server is identified (in events, avatar URLs, etc.) by a URI with a mxc scheme (mxc://matrix.org/xxxx for example). To obtain the underlying HTTP URI for retrieving the content, use
where contentUrl is the mxc:// content URL.
For images, an additional method exists for returning thumbnails instead of full-sized images:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
which allows you to request a specific width, height, and scale method (between scale and crop).
To upload content from a file, use
specifying the file path and a callback method which will return an object on completion containing the mxc-style URI where the uploaded content can now be found.
See the sample app and Javadoc for more details.