Awesome
Matrix JavaScript SDK
This is the Matrix Client-Server SDK for JavaScript and TypeScript. This SDK can be run in a browser or in Node.js.
Minimum Matrix server version: v1.1
The Matrix specification is constantly evolving - while this SDK aims for maximum backwards compatibility, it only guarantees that a feature will be supported for at least 4 spec releases. For example, if a feature the js-sdk supports is removed in v1.4 then the feature is eligible for removal from the SDK when v1.8 is released. This SDK has no guarantee on implementing all features of any particular spec release, currently. This can mean that the SDK will call endpoints from before Matrix 1.1, for example.
Quickstart
[!IMPORTANT] Servers may require or use authenticated endpoints for media (images, files, avatars, etc). See the Authenticated Media section for information on how to enable support for this.
Using yarn
instead of npm
is recommended. Please see the Yarn install guide
if you do not have it already.
yarn add matrix-js-sdk
import * as sdk from "matrix-js-sdk";
const client = sdk.createClient({ baseUrl: "https://matrix.org" });
client.publicRooms(function (err, data) {
console.log("Public Rooms: %s", JSON.stringify(data));
});
See below for how to include libolm to enable end-to-end-encryption. Please check the Node.js terminal app for a more complex example.
To start the client:
await client.startClient({ initialSyncLimit: 10 });
You can perform a call to /sync
to get the current state of the client:
client.once(ClientEvent.sync, function (state, prevState, res) {
if (state === "PREPARED") {
console.log("prepared");
} else {
console.log(state);
process.exit(1);
}
});
To send a message:
const content = {
body: "message text",
msgtype: "m.text",
};
client.sendEvent("roomId", "m.room.message", content, "", (err, res) => {
console.log(err);
});
To listen for message events:
client.on(RoomEvent.Timeline, function (event, room, toStartOfTimeline) {
if (event.getType() !== "m.room.message") {
return; // only use messages
}
console.log(event.event.content.body);
});
By default, the matrix-js-sdk
client uses the MemoryStore
to store events as they are received. For example to iterate through the currently stored timeline for a room:
Object.keys(client.store.rooms).forEach((roomId) => {
client.getRoom(roomId).timeline.forEach((t) => {
console.log(t.event);
});
});
Authenticated media
Servers supporting MSC3916 (Matrix 1.11) will require clients, like
yours, to include an Authorization
header when /download
ing or /thumbnail
ing media. For NodeJS environments this
may be as easy as the following code snippet, though web browsers may need to use Service Workers
to append the header when using the endpoints in <img />
elements and similar.
const downloadUrl = client.mxcUrlToHttp(
/*mxcUrl=*/ "mxc://example.org/abc123", // the MXC URI to download/thumbnail, typically from an event or profile
/*width=*/ undefined, // part of the thumbnail API. Use as required.
/*height=*/ undefined, // part of the thumbnail API. Use as required.
/*resizeMethod=*/ undefined, // part of the thumbnail API. Use as required.
/*allowDirectLinks=*/ false, // should generally be left `false`.
/*allowRedirects=*/ true, // implied supported with authentication
/*useAuthentication=*/ true, // the flag we're after in this example
);
const img = await fetch(downloadUrl, {
headers: {
Authorization: `Bearer ${client.getAccessToken()}`,
},
});
// Do something with `img`.
[!WARNING] In future the js-sdk will only return authentication-required URLs, mandating population of the
Authorization
header.
What does this SDK do?
This SDK provides a full object model around the Matrix Client-Server API and emits events for incoming data and state changes. Aside from wrapping the HTTP API, it:
- Handles syncing (via
/sync
) - Handles the generation of "friendly" room and member names.
- Handles historical
RoomMember
information (e.g. display names). - Manages room member state across multiple events (e.g. it handles typing, power levels and membership changes).
- Exposes high-level objects like
Rooms
,RoomState
,RoomMembers
andUsers
which can be listened to for things like name changes, new messages, membership changes, presence changes, and more. - Handle "local echo" of messages sent using the SDK. This means that messages that have just been sent will appear in the timeline as 'sending', until it completes. This is beneficial because it prevents there being a gap between hitting the send button and having the "remote echo" arrive.
- Mark messages which failed to send as not sent.
- Automatically retry requests to send messages due to network errors.
- Automatically retry requests to send messages due to rate limiting errors.
- Handle queueing of messages.
- Handles pagination.
- Handle assigning push actions for events.
- Handles room initial sync on accepting invites.
- Handles WebRTC calling.
Usage
Supported platforms
matrix-js-sdk
can be used in either Node.js applications (ensure you have the latest LTS version of Node.js installed),
or in browser applications, via a bundler such as Webpack or Vite.
You can also use the sdk with Deno (import npm:matrix-js-sdk
) but its not officialy supported.
Emitted events
The SDK raises notifications to the application using
EventEmitter
s. The MatrixClient
itself
implements EventEmitter
, as do many of the high-level abstractions such as Room
and RoomMember
.
// Listen for low-level MatrixEvents
client.on(ClientEvent.Event, function (event) {
console.log(event.getType());
});
// Listen for typing changes
client.on(RoomMemberEvent.Typing, function (event, member) {
if (member.typing) {
console.log(member.name + " is typing...");
} else {
console.log(member.name + " stopped typing.");
}
});
// start the client to setup the connection to the server
client.startClient();
Entry points
As well as the primary entry point (matrix-js-sdk
), there are several other entry points which may be useful:
Entry point | Description |
---|---|
matrix-js-sdk | Primary entry point. High-level functionality, and lots of historical clutter in need of a cleanup. |
matrix-js-sdk/lib/crypto-api | Cryptography functionality. |
matrix-js-sdk/lib/types | Low-level types, reflecting data structures defined in the Matrix spec. |
matrix-js-sdk/lib/testing | Test utilities, which may be useful in test code but should not be used in production code. |
Examples
This section provides some useful code snippets which demonstrate the core functionality of the SDK. These examples assume the SDK is set up like this:
import * as sdk from "matrix-js-sdk";
const myUserId = "@example:localhost";
const myAccessToken = "QGV4YW1wbGU6bG9jYWxob3N0.qPEvLuYfNBjxikiCjP";
const matrixClient = sdk.createClient({
baseUrl: "http://localhost:8008",
accessToken: myAccessToken,
userId: myUserId,
});
Automatically join rooms when invited
matrixClient.on(RoomEvent.MyMembership, function (room, membership, prevMembership) {
if (membership === KnownMembership.Invite) {
matrixClient.joinRoom(room.roomId).then(function () {
console.log("Auto-joined %s", room.roomId);
});
}
});
matrixClient.startClient();
Print out messages for all rooms
matrixClient.on(RoomEvent.Timeline, function (event, room, toStartOfTimeline) {
if (toStartOfTimeline) {
return; // don't print paginated results
}
if (event.getType() !== "m.room.message") {
return; // only print messages
}
console.log(
// the room name will update with m.room.name events automatically
"(%s) %s :: %s",
room.name,
event.getSender(),
event.getContent().body,
);
});
matrixClient.startClient();
Output:
(My Room) @megan:localhost :: Hello world
(My Room) @megan:localhost :: how are you?
(My Room) @example:localhost :: I am good
(My Room) @example:localhost :: change the room name
(My New Room) @megan:localhost :: done
Print out membership lists whenever they are changed
matrixClient.on(RoomStateEvent.Members, function (event, state, member) {
const room = matrixClient.getRoom(state.roomId);
if (!room) {
return;
}
const memberList = state.getMembers();
console.log(room.name);
console.log(Array(room.name.length + 1).join("=")); // underline
for (var i = 0; i < memberList.length; i++) {
console.log("(%s) %s", memberList[i].membership, memberList[i].name);
}
});
matrixClient.startClient();
Output:
My Room
=======
(join) @example:localhost
(leave) @alice:localhost
(join) Bob
(invite) @charlie:localhost
API Reference
A hosted reference can be found at http://matrix-org.github.io/matrix-js-sdk/index.html
This SDK uses Typedoc doc comments. You can manually build and host the API reference from the source files like this:
$ yarn gendoc
$ cd docs
$ python -m http.server 8005
Then visit http://localhost:8005
to see the API docs.
End-to-end encryption support
This section is outdated. Use of libolm
is deprecated and we are replacing it with support
from the matrix-rust-sdk (https://github.com/element-hq/element-web/issues/21972).
The SDK supports end-to-end encryption via the Olm and Megolm protocols, using
libolm. It is left up to the
application to make libolm available, via the Olm
global.
It is also necessary to call await matrixClient.initCrypto()
after creating a new
MatrixClient
(but before calling matrixClient.startClient()
) to
initialise the crypto layer.
If the Olm
global is not available, the SDK will show a warning, as shown
below; initCrypto()
will also fail.
Unable to load crypto module: crypto will be disabled: Error: global.Olm is not defined
If the crypto layer is not (successfully) initialised, the SDK will continue to work for unencrypted rooms, but it will not support the E2E parts of the Matrix specification.
To provide the Olm library in a browser application:
- download the transpiled libolm (from https://packages.matrix.org/npm/olm/).
- load
olm.js
as a<script>
beforebrowser-matrix.js
.
To provide the Olm library in a node.js application:
yarn add https://packages.matrix.org/npm/olm/olm-3.1.4.tgz
(replace the URL with the latest version you want to use from https://packages.matrix.org/npm/olm/)global.Olm = require('olm');
before loadingmatrix-js-sdk
.
If you want to package Olm as dependency for your node.js application, you can
use yarn add https://packages.matrix.org/npm/olm/olm-3.1.4.tgz
. If your
application also works without e2e crypto enabled, add --optional
to mark it
as an optional dependency.
Contributing
This section is for people who want to modify the SDK. If you just want to use this SDK, skip this section.
First, you need to pull in the right build tools:
$ yarn install
Building
To build a browser version from scratch when developing:
$ yarn build
To run tests (Jest):
$ yarn test
To run linting:
$ yarn lint