A lightweight version of the matrix-js-sdk intended for bots. For help and support, visit #matrix-bot-sdk:t2bot.io
Documentation for the develop branch is available here.
Templates and guides
This package can be found on npm:
npm install matrix-bot-sdk
Here's an example of a very simple bot written using this library. It will auto-join rooms and respond to
!hello as a command.
;// where you would point a client to talk to a homeserver;// see;// We'll want to make sure the bot doesn't have to do an initial sync every// time it restarts, so we need to prepare a storage provider. Here we use// a simple JSON database.;// Now we can create the client and set it up to automatically join rooms.;AutojoinRoomsMixin.setupOnClientclient;// We also want to make sure we can receive events - this is where we will// handle our command.client.on"room.message", handleCommand;// Now that the client is all set up and the event handler is registered, start the// client up. This will start it syncing.client.start.thenconsole.log"Client started!";// This is our event handler for dealing with the `!hello` command.
;;;AutojoinRoomsMixin.setupOnClientclient;// To listen for room messages (m.room.message) only:client.on"room.message",;// Or to listen for any event that happens in a room:client.on"room.event",;client.start.thenconsole.log"Client started!";
To automatically process rich replies coming into the client:
;;;;// Set fetchRealEventContents to true to have the preprocessor get the real eventclient.addPreprocessornew RichRepliesPreprocessorfetchRealEventContents: false;// regular client usage here. When you encounter an event:;if event
To send a rich reply to an event:
Note: If you plan on using application services, you'll need to install the
peerDependencies of this project.
Application service support is an experimental feature of the SDK. This does things like Intent management, impersonation, and transaction handling on behalf of the application.
You'll need to load your registration file from somewhere, however the fastest path is:
const Appservice = Appservice;// The registration is of type AppserviceRegistration, also available from the matrix-bot-sdkconst registration =as_token: "YourTokenHere"hs_token: "YourTokenHere"sender_localpart: "_some_bridge"namespaces:users:exclusive: trueregex: "@_some_bridge_.*"rooms:aliases:;// The options are of type AppserviceOptions, also available from the matrix-bot-sdkconst options =port: 9000bindAddress: "0.0.0.0"homeserverName: "matrix.org"homeserverUrl: "";const appservice = options registration;appservice;// or if you don't want to do your own parsing to figure out the user prefix:appservice;
When a room is upgraded, bots and bridges might have to relocate data to the new room. This SDK can handle the easier part of ensuring the bot/bridge is in the new room, and emits events to make the remainder of the process a little easier.
An upgrade happens in two phases: a
room.archived phase where the old room is flagged as being replaced by another room and a
room.upgraded phase once the bot/bridge is aware of the new room. Bots and appservices can be told to automatically try and join the new room by attaching a
AutojoinUpgradedRoomsMixin to the client/appservice, much like the
Bots and appservices should listen for
room.upgraded to perform a data transfer as this is when there is referential integrity between the two rooms. Prior to an upgrade, there is no guarantee that the replacement room advertised is actually valid.
To get the full chain of rooms, use
getRoomUpgradeHistory(roomId) on a
MatrixClient (ie: the
botIntent.underlyingClient or your own).