In a browser
Download either the full or minified version from
https://github.com/matrix-org/matrix-js-sdk/releases/latest and add that as a
<script> to your page. There will be a global variable
window through which you can access the SDK. See below for how to
include libolm to enable end-to-end-encryption.
Please check the working browser example for more information.
npm install matrix-js-sdk
var sdk = ;var client = sdk;client;
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.
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
- Handles the generation of "friendly" room and member names.
- Handles historical
RoomMemberinformation (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
Userswhich 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.
Later versions of the SDK will:
- Expose a
RoomSummarywhich would be suitable for a recents page.
- Provide different pluggable storage layers (e.g. local storage, database-backed)
The SDK will emit events using an
EventEmitter. It also
emits object models (e.g.
RoomMembers) when they
// Listen for low-level MatrixEventsclient;// Listen for typing changesclient;// start the client to setup the connection to the serverclient;
Promises and Callbacks
Most of the methods in the SDK are asynchronous: they do not directly return a result, but instead return a Promise which will be fulfilled in the future.
The typical usage is something like:
Alternatively, if you have a Node.js-style
callback(err, result) function,
you can pass the result of the promise into it with something like:
The main thing to note is that it is an error to discard the result of a
promise-returning function, as that will cause exceptions to go unobserved. If
you have nothing better to do with the result, just call
.done() on it. See
http://documentup.com/kriskowal/q/#the-end for more information.
Methods which return a promise show this in their documentation.
Many methods in the SDK support both Node.js-style callbacks and Promises,
via an optional
callback argument. The callback support is now deprecated:
new methods do not include a
callback argument, and in the future it may be
removed from existing methods.
This section provides some useful code snippets which demonstrate the core functionality of the SDK. These examples assume the SDK is setup like this:
var sdk = ;var myUserId = "@example:localhost";var myAccessToken = "QGV4YW1wbGU6bG9jYWxob3N0.qPEvLuYfNBjxikiCjP";var matrixClient = sdk;
Automatically join rooms when invited
Print out messages for all rooms
(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
My Room ======= (join) @example:localhost (leave) @alice:localhost (join) Bob (invite) @charlie:localhost
A hosted reference can be found at http://matrix-org.github.io/matrix-js-sdk/index.html
This SDK uses JSDoc3 style comments. You can manually build and host the API reference from the source files like this:
$ npm run gendoc $ cd .jsdoc $ python -m SimpleHTTPServer 8005
http://localhost:8005 to see the API docs.
End-to-end encryption support
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
It is also necessry to call
matrixClient.initCrypto() after creating a new
MatrixClient (but before calling
initialise the crypto layer.
Olm global is not available, the SDK will show a warning, as shown
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://matrix.org/packages/npm/olm/).
To provide the Olm library in a node.js application:
npm install https://matrix.org/packages/npm/olm/olm-2.2.2.tgz(replace the URL with the latest version you want to use from https://matrix.org/packages/npm/olm/)
global.Olm = require('olm');before loading
If you want to package Olm as dependency for your node.js application, you
npm install https://matrix.org/packages/npm/olm/olm-2.2.2.tgz --save-optional (if your application also works without e2e crypto enabled)
--save (if it doesn't) to do so.
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:
$ npm install
To build a browser version from scratch when developing::
$ npm run build
To constantly do builds when files are modified (using
$ npm run watch
To run tests (Jasmine)::
$ npm test
To run linting:
$ npm run lint