Matrix JavaScript SDK

Build real-time messaging, end-to-end encryption, and VoIP calling into your JavaScript or TypeScript applications with the Matrix protocol.

The Matrix JavaScript SDK is a comprehensive TypeScript/JavaScript library for building Matrix protocol clients. It handles everything from real-time sync and room management to end-to-end encryption and VoIP calling — in both browser and Node.js environments.

Quickstart

Get a working Matrix client up and running in minutes

Installation

Install the SDK and learn about entry points and package managers

Core Concepts

Understand the MatrixClient, rooms, events, and sync lifecycle

API Reference

Explore the full MatrixClient API with types and examples

Getting started

1. Install the SDK

   Add matrix-js-sdk to your project using your preferred package manager.

   pnpm add matrix-js-sdk
   
2. Create a client

   Use createClient to connect to a Matrix homeserver.

   import { createClient } from "matrix-js-sdk";
   
   const client = createClient({
     baseUrl: "https://matrix.org",
     accessToken: "YOUR_ACCESS_TOKEN",
     userId: "@you:matrix.org",
   });
   
3. Start syncing

   Call startClient to begin receiving real-time events.

   await client.startClient({ initialSyncLimit: 10 });
   
4. Listen for messages

   Attach event listeners to respond to Matrix events in real time.

   import { RoomEvent } from "matrix-js-sdk";
   
   client.on(RoomEvent.Timeline, (event, room) => {
     if (event.getType() === "m.room.message") {
       console.log(`[${room.name}] ${event.getSender()}: ${event.getContent().body}`);
     }
   });
   

What you can build

Messaging apps

Build full-featured chat clients with rooms, threads, and reactions

Encrypted communication

Add end-to-end encryption with cross-signing and key backup

VoIP and video

Enable 1:1 and group calls with WebRTC and MatrixRTC/LiveKit

Bot integrations

Create automated bots that interact with Matrix rooms

Embedded widgets

Build Matrix-aware widgets with the widget client API

OIDC authentication

Integrate modern OAuth 2.0 / OIDC login flows

Key features

• Full Matrix Client-Server API — complete coverage of the Matrix specification
• End-to-end encryption — powered by the Rust WebAssembly crypto stack (matrix-sdk-crypto)
• Real-time sync — traditional /sync and modern Sliding Sync (MSC4186) support
• VoIP calling — 1:1 calls and group calling via MatrixRTC and LiveKit
• OIDC support — modern authentication with oidc-client-ts
• Browser and Node.js — runs in web browsers via bundlers and in Node.js 22+
• TypeScript-first — full type safety with comprehensive type definitions

The minimum supported Matrix server version is v1.1. Node.js 22+ is required for server-side usage.