Matrix

https://matrix.org/docs/
Admin
Matrix is an open protocol for decentralized, federated real-time communication supporting instant...
Tokens:51,995
Snippets:419
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start the client

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Start the client and log a message when it starts successfully.

```javascript
client.start().then(() => console.log("Client started!"));

```

--------------------------------

### Install matrix-bot-sdk and create project directory

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Run these bash commands to create a new folder and install the matrix-bot-sdk npm package.

```bash
mkdir matrix-js-echo-bot
cd matrix-js-echo-bot
npm install matrix-bot-sdk

```

--------------------------------

### Complete index.js example

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

The full example code for index.js, combining all the previous steps.

```javascript
import {
    MatrixClient,
    SimpleFsStorageProvider,
    AutojoinRoomsMixin
} from "matrix-bot-sdk";

const homeserverUrl = "https://matrix.org"; // make sure to update this with your url
const accessToken = "YourSecretAccessToken";
const storage = new SimpleFsStorageProvider("bot.json");

const client = new MatrixClient(homeserverUrl, accessToken, storage);
AutojoinRoomsMixin.setupOnClient(client);

client.start().then(() => console.log("Client started!"));

```

--------------------------------

### Room alias example

Source: https://matrix.org/docs/matrix-concepts/rooms_and_events

Example of a typical room alias, consisting of a room name and a server part.

```text
#goodfriends:example.com
```

--------------------------------

### Federation media response with Location header

Source: https://matrix.org/docs/spec-guides/authed-media-servers

Example of a `multipart/mixed` response where the second part uses a `Location` header to point to the actual file. Servers must make a regular GET request to that URL to fetch the media; `Content-Type` and `Content-Disposition` headers are present on that URL.

```http
Content-Type: multipart/mixed; boundary=gc0p4Jq0M2Yt08jU534c0p

--gc0p4Jq0M2Yt08jU534c0p
Content-Type: application/json

{}

--gc0p4Jq0M2Yt08jU534c0p
Location: https://cdn.example.org/ab/c1/2345.txt

--gc0p4Jq0M2Yt08jU534c0p

```

--------------------------------

### Unpadded Base64 Encoding Examples

Source: https://matrix.org/docs/spec/appendices.html

Examples of strings encoded using unpadded Base64, showing the output for inputs from empty string to 'foobar'. Note the absence of '=' padding.

```text
UNPADDED_BASE64("") = ""
UNPADDED_BASE64("f") = "Zg"
UNPADDED_BASE64("fo") = "Zm8"
UNPADDED_BASE64("foo") = "Zm9v"
UNPADDED_BASE64("foob") = "Zm9vYg"
UNPADDED_BASE64("fooba") = "Zm9vYmE"
UNPADDED_BASE64("foobar") = "Zm9vYmFy"
```

--------------------------------

### Install TypeScript compiler with npm

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Installs the TypeScript compiler (tsc) via npm. Run this before using tsc to compile TypeScript files.

```bash
npm install typescript

```

--------------------------------

### Matrix event JSON example

Source: https://matrix.org/docs/matrix-concepts/rooms_and_events

Example of a Matrix event object, showing a message with HTML formatting and metadata such as event_id, room_id, and sender.

```json
{
  "content": {
    "body": "This is an example text message",
    "format": "org.matrix.custom.html",
    "formatted_body": "<b>This is an example text message</b>",
    "msgtype": "m.text"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "type": "m.room.message",
  "unsigned": {
    "age": 1234
  }
}
```

--------------------------------

### Canonical JSON example: keys sorted alphabetically

Source: https://matrix.org/docs/spec/appendices.html

Input and output for an object with keys 'b' and 'a', demonstrating key sorting.

```json
{
    "b": "2",
    "a": "1"
}

```

```json
{"a":"1","b":"2"}

```

--------------------------------

### matrix.to URI examples for room alias, room, permalinks, user, and group

Source: https://matrix.org/docs/spec/appendices.html

These are example matrix.to URIs for different identifier types: room alias, room, permalink by room, permalink by room alias, user, and group. The URIs are percent-encoded as per RFC 3986. Clients should try to interpret unencoded URIs and should encode extra slashes that may appear when decoding.

```text
https://matrix.to/#/%23somewhere%3Aexample.org
```

```text
https://matrix.to/#/!somewhere%3Aexample.org
```

```text
https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org
```

```text
https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org
```

```text
https://matrix.to/#/%40alice%3Aexample.org
```

```text
https://matrix.to/#/%2Bexample%3Aexample.org
```

--------------------------------

### Canonical JSON example: simple object with two keys

Source: https://matrix.org/docs/spec/appendices.html

Input and output for a simple object with keys 'one' and 'two', showing compact formatting and key sorting.

```json
{
    "one": 1,
    "two": "Two"
}

```

```json
{"one":1,"two":"Two"}

```

--------------------------------

### Canonical JSON example: compact input with unsorted keys

Source: https://matrix.org/docs/spec/appendices.html

Input and output for a compact JSON object with unsorted keys, showing sorting and compact output.

```json
{"b":"2","a":"1"}

```

```json
{"a":"1","b":"2"}

```

--------------------------------

### Configure SimpleFsStorageProvider

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Create a storage provider instance that will store bot data in a file named 'bot.json'.

```javascript
const storage = new SimpleFsStorageProvider("bot.json");

```

--------------------------------

### Create a ban list with !mjolnir list create

Source: https://matrix.org/docs/communities/moderation

Use this command to create a ban list. The first block shows the general syntax; the second creates a ban list with shortcode 'spam' and address '#my-community-spam-ban-list:example.com' (assuming the server is example.com). You only need to create a ban list once, and can then add users and servers to it.

```text
!mjolnir list create <shortcode> <alias localpart>

```

```text
!mjolnir list create spam my-community-spam-ban-list

```

--------------------------------

### Import matrix-bot-sdk modules

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Import the required classes from the SDK: MatrixClient, SimpleFsStorageProvider, and AutojoinRoomsMixin.

```javascript
const sdk = require("matrix-bot-sdk");
const MatrixClient = sdk.MatrixClient;
const SimpleFsStorageProvider = sdk.SimpleFsStorageProvider;
const AutojoinRoomsMixin = sdk.AutojoinRoomsMixin;

```

--------------------------------

### Instantiate MatrixClient

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Create the MatrixClient instance using the homeserver URL, access token, and storage provider.

```javascript
const client = new MatrixClient(homeserverUrl, accessToken, storage);

```

--------------------------------

### Set up autojoin rooms mixin

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Add the AutojoinRoomsMixin to the client so it automatically accepts room invites.

```javascript
AutojoinRoomsMixin.setupOnClient(client);

```

--------------------------------

### Sync messages with long-lived GET request

Source: https://matrix.org/docs/matrix-concepts/elements-of-matrix

Destination clients receive messages via a long-lived GET request to the sync endpoint. The response includes the next_batch token and the room timeline events.

```bash
curl "https://matrix.bob.com/_matrix/client/v3/sync" \
    -H "Authorization: Bearer ACCESS_TOKEN"
{
  "next_batch": "s72595_4483_1934",
  "rooms": {
    ...
    "join": {
      ...
      "ROOM_ID": {
        ...
        "timeline": {
          "events": [
            {
              "event_id": "$YUwRidLecu:alice.com",
              "type": "m.room.message",
              "content": {
                "body": "hello",
                "msgtype": "m.text"
              },
              "origin_server_ts": 1417731086797,
              "sender": "@alice:alice.com"
            }
          ]
          ...
        }
      }
    }
  }
  ...
}
```

--------------------------------

### Run the bot with node

Source: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk

Execute the bot script using Node.js.

```bash
node index.js

```

--------------------------------

### Matrix room v2 event example

Source: https://matrix.org/docs/spec/rooms/v2

Example of a Matrix event in room version 2, showing the full structure including auth_events, prev_events, hashes, signatures, and unsigned fields. This is the canonical event format for this room version.

```json
{
  "auth_events": [
    [
      "$af232176:example.org",
      {
        "sha256": "abase64encodedsha256hashshouldbe43byteslong"
      }
    ]
  ],
  "content": {
    "key": "value"
  },
  "depth": 12,
  "event_id": "$a4ecee13e2accdadf56c1025:example.com",
  "hashes": {
    "sha256": "thishashcoversallfieldsincasethisisredacted"
  },
  "origin_server_ts": 1404838188000,
  "prev_events": [
    [
      "$af232176:example.org",
      {
        "sha256": "abase64encodedsha256hashshouldbe43byteslong"
      }
    ]
  ],
  "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
  "sender": "@alice:example.com",
  "signatures": {
    "example.com": {
      "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
    }
  },
  "type": "m.room.message",
  "unsigned": {
    "age": 4612
  }
}
```

--------------------------------

### Signing JSON with ed25519: example and sign_json function

Source: https://matrix.org/docs/spec/appendices.html

The JSON example shows a signed event with a signing key, an unsigned object, and a signature. The Python function sign_json removes signatures and unsigned, signs the canonical JSON, and adds the signature back.

```json
{
   "name": "example.org",
   "signing_keys": {
     "ed25519:1": "XSl0kuyvrXNj6A+7/tkrB9sxSbRi08Of5uRhxOqZtEQ"
   },
   "unsigned": {
      "age_ts": 922834800000
   },
   "signatures": {
      "example.org": {
         "ed25519:1": "s76RUgajp8w172am0zQb/iPTHsRnb4SkrzGoeCOSFfcBY2V/1c8QfrmdXHpvnc2jK5BD1WiJIxiMW95fMjK7Bw"
      }
   }
}

```

```python
def sign_json(json_object, signing_key, signing_name):
    signatures = json_object.pop("signatures", {})
    unsigned = json_object.pop("unsigned", None)

    signed = signing_key.sign(encode_canonical_json(json_object))
    signature_base64 = encode_base64(signed.signature)

    key_id = "%s:%s" % (signing_key.alg, signing_key.version)
    signatures.setdefault(signing_name, {})[key_id] = signature_base64

    json_object["signatures"] = signatures
    if unsigned is not None:
        json_object["unsigned"] = unsigned

    return json_object

```

--------------------------------

### Canonical JSON example: empty object

Source: https://matrix.org/docs/spec/appendices.html

Input and output for an empty JSON object, which remains unchanged.

```json
{}

```

```json
{}

```
Tokens:
Raw