167 lines
7.1 KiB
Markdown
167 lines
7.1 KiB
Markdown
---
|
|
page-title: "Usage of matrix-bot-sdk | Matrix.org"
|
|
url: https://matrix.org/docs/guides/usage-of-matrix-bot-sdk
|
|
date: "2023-04-18 13:34:11"
|
|
---
|
|
This article concerns [matrix-bot-sdk](https://github.com/turt2live/matrix-bot-sdk), a TypeScript client SDK for Matrix. We'll build a simple "echo bot", meaning a bot which replies to messages with the text it has just read.
|
|
|
|
Note that although the SDK is written in TypeScript, we'll use JavaScript in our examples. If you'd prefer to use TypeScript, then do!
|
|
|
|
## [](https://matrix.org/docs/guides/usage-of-matrix-bot-sdk#setup)Setup
|
|
|
|
Let's make a new folder, and import our only npm dependency. The following examples are all meant to be run in a bash terminal.
|
|
|
|
```
|
|
mkdir matrix-js-echo-bot
|
|
cd matrix-js-echo-bot
|
|
npm install matrix-bot-sdk
|
|
```
|
|
|
|
Create a new file named "index.js", and let's get started.
|
|
|
|
## [](https://matrix.org/docs/guides/usage-of-matrix-bot-sdk#instantiation)Instantiation
|
|
|
|
In our js file, start by importing the minimum we'll need for this example:
|
|
|
|
```
|
|
const sdk = require("matrix-bot-sdk");
|
|
const MatrixClient = sdk.MatrixClient;
|
|
const SimpleFsStorageProvider = sdk.SimpleFsStorageProvider;
|
|
const AutojoinRoomsMixin = sdk.AutojoinRoomsMixin;
|
|
```
|
|
|
|
Create a new account for your bot on a homeserver, then get the `access_token`. The simplest way to do this is using Element, [take a look at these instructions](https://t2bot.io/docs/access_tokens/). Set some variables to store the homeserver and `access_token`. This is all the authentication you need!
|
|
|
|
```
|
|
const homeserverUrl = "https://matrix.org"; // make sure to update this with your url
|
|
const accessToken = "YourSecretAccessToken";
|
|
```
|
|
|
|
Now we'll configure a storage provider - matrix-bot-sdk provides the `SimpleFsStorageProvider`, which is ideal for most cases:
|
|
|
|
```
|
|
const storage = new SimpleFsStorageProvider("bot.json");
|
|
```
|
|
|
|
When the bot starts, the SDK will create a a new file called "bot.json" to store the data it needs.
|
|
|
|
Finally we're ready to start the client! As you'd expect, we'll use the variables we've already specified.
|
|
|
|
```
|
|
const client = new MatrixClient(homeserverUrl, accessToken, storage);
|
|
```
|
|
|
|
There is one more thing we need to do. We'll include a mixin which instructs the bot to auto-accept any room invite it receives. This makes testing much more convenient.
|
|
|
|
```
|
|
AutojoinRoomsMixin.setupOnClient(client);
|
|
```
|
|
|
|
Finally, let's start the Client:
|
|
|
|
```
|
|
client.start().then(() => console.log("Client started!"));
|
|
```
|
|
|
|
If you're keeping up, your code should look something like:
|
|
|
|
```
|
|
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!"));
|
|
```
|
|
|
|
Let's run it:
|
|
|
|
This should now join and sit idle, but join any room you invite the bot to.
|
|
|
|
## [](https://matrix.org/docs/guides/usage-of-matrix-bot-sdk#sync-loop)/sync loop
|
|
|
|
Right now, while it's just listening to invites and nothing else, what is the bot actually doing? It's calling the `/sync` endpoint in a loop. Calling this endpoint returns all new events since some previous point.
|
|
|
|
Leave the script running and open `bot.json`, which is the file we specified for storage. This file contains a field `syncToken`, which is being occasionally updated - the SDK uses this field to give a token to the homeserver, which uses it to know which events to send back.
|
|
|
|
## [](https://matrix.org/docs/guides/usage-of-matrix-bot-sdk#receiving-and-sending-events)Receiving and Sending events
|
|
|
|
In order to echo messages, our bot must first be able to read them. The `client.on()` method of our MatrixClient takes two arguments: one for the event type, one for a callback to handle the event:
|
|
|
|
```
|
|
client.on("room.message", (roomId, event) => {
|
|
if (! event["content"]) return;
|
|
const sender = event["sender"];
|
|
const body = event["content"]["body"];
|
|
console.log(`${roomId}: ${sender} says '${body}`);
|
|
});
|
|
```
|
|
|
|
In this way we can inspect an the contents of an event and render them. We choose to exit early in the case that `event["content"]` is empty because this will usually mean the message was redacted.
|
|
|
|
To send a message, we use the `client.sendMessage()` method. This takes two arguments: the roomId, and a JSON object containing the contents of the message to send, for example:
|
|
|
|
```
|
|
client.sendMessage(roomId, {
|
|
"msgtype": "m.text",
|
|
"body": "This is message text.",
|
|
});
|
|
```
|
|
|
|
Note, it's also possible to use `client.sendText()` to achieve the same result, as in
|
|
|
|
```
|
|
client.sendText(roomId, "This is message text.")
|
|
```
|
|
|
|
The reason for showing `client.sendMessage()` is to make it clear that the message format is [just the same as you'd find in the spec](https://matrix.org/docs/spec/client_server/latest#put-matrix-client-r0-rooms-roomid-send-eventtype-txnid).
|
|
|
|
## [](https://matrix.org/docs/guides/usage-of-matrix-bot-sdk#implementing-echobot-functionality)Implementing echobot functionality
|
|
|
|
To work, an echobot needs only to listen for incoming messages, read the message text, and use it to reply. Let's demonstrate that now.
|
|
|
|
- Read the message as in the example above
|
|
- Inspect the body text, if it starts with "!echo", send back the remaining text
|
|
- Strip out the "!echo" tag
|
|
- Send a message containing the result
|
|
|
|
```
|
|
client.on("room.message", (roomId, event) => {
|
|
if (! event["content"]) return;
|
|
const sender = event["sender"];
|
|
const body = event["content"]["body"];
|
|
console.log(`${roomId}: ${sender} says '${body}`);
|
|
|
|
if (body.startsWith("!echo")) {
|
|
const replyText = body.substring("!echo".length).trim();
|
|
client.sendMessage(roomId, {
|
|
"msgtype": "m.notice",
|
|
"body": replyText,
|
|
});
|
|
}
|
|
});
|
|
```
|
|
|
|
## [](https://matrix.org/docs/guides/usage-of-matrix-bot-sdk#conclusion)Conclusion
|
|
|
|
It's extremely simple to listen to messages with [matrix-bot-sdk](https://github.com/turt2live/matrix-bot-sdk) create an echobot! There are many more features, you can see the MatrixClient class is [very well documented](https://github.com/turt2live/matrix-bot-sdk/blob/master/src/MatrixClient.ts). Next in this series, we'll explore Rich Replies, and take a look at the kick and ban functions for room administration.
|
|
|
|
## [](https://matrix.org/docs/guides/usage-of-matrix-bot-sdk#ps-use-typescript)PS, use TypeScript
|
|
|
|
This SDK uses TypeScript, which provides a lot of benefits. In this example, we used JavaScript, but it's just as easy to use TypeScript and maybe preferable, since it is the language [matrix-bot-sdk](https://github.com/turt2live/matrix-bot-sdk) is written in.
|
|
|
|
First let's install `tsc`, which compiles from TypeScript to JavaScript:
|
|
|
|
Now, start tsc in watch-mode (`-w`), and leave it to compile our code:
|
|
|
|
Now, whenever we create a new TypeScript (`.ts`) file, it will be automatically watched and compiled to JavaScript.
|
|
|
|
When you have your .js file(s), you can run them with `node <filename>` as normal. |