Matrix Helper Bot (Appservice)

A minimal example bot built with matrix-bot-sdk running as a Matrix application service. It can send normal text, images, and videos.

Files

• bot.ts — the bot implementation (TypeScript).
• AGENT.md — instructions for automated agents working in this repo.

Setup example

1. Create a registration file (e.g. registration.yaml) and install it on your homeserver per your homeserver's appservice docs:

id: examplebot
as_token: <RANDOM STRING>
hs_token: <RANDOM STRING>
url: "http://localhost:9000"
sender_localpart: "bot"
namespaces:
  users: [{ exclusive: true, regex: "@bot.+" }]
  aliases: []
  rooms: []
rate_limited: false
de.sorunome.msc2409.push_ephemeral: true

2. Copy the as_token/hs_token and homeserver details into bot.ts.
3. Install dependencies and run (do this yourself; agents must not run setup):

npm install
npx ts-node bot.ts

Note: typescript is pinned to the 5.8.x line in package.json because ts-node 10.9.x is not compatible with TypeScript 7.x. If you already installed TypeScript 7.x, run npm install typescript@~5.8.3 (or remove node_modules and reinstall) before starting the bot.

No setup is performed by this repository. Do not run install/build steps on behalf of the user unless asked.

Access control

Edit access.json (or set ACCESS_FILE) to restrict who can use bot commands:

{
  "allowedUsers": ["@alice:example.org"],
  "allowedServers": ["example.org"]
}

• allowedUsers: exact Matrix user IDs (e.g. @user:host.de).
• allowedServers: homeserver names (e.g. host.de), allowing every user from that server.

If both lists are empty, everyone is allowed.

Command access

You can also restrict which commands a user or server may use. Command entries may be command names (e.g. !webhook) or category names (basic, media, webhook, help), or */all for everything:

{
  "allowedUsers": [],
  "allowedServers": [],
  "users": {
    "@alice:example.org": ["basic", "!webhook"]
  },
  "servers": {
    "example.org": ["media"]
  },
  "default": ["basic", "help"]
}

If no command restrictions are configured for a user, all commands are allowed.

Updating the bot over Git

registration.yaml (and possibly bot.ts) may contain your real tokens/URLs, so back them up before pulling to avoid merge conflicts or overwriting secrets.

cd /home/kotarou/matrix-helper-bot
# Back up local secrets/config
cp registration.yaml /tmp/registration.yaml.bak
# Stash any other local edits
git stash
git pull
# Restore your secrets/config if the pull changed them
cp /tmp/registration.yaml.bak registration.yaml
# Reapply stashed edits (resolve conflicts if needed)
git stash pop
# Reinstall dependencies only if package.json changed
npm install
# Restart the running service
sudo systemctl restart matrix-helper-bot

If you run it manually instead of systemd:

cd /home/kotarou/matrix-helper-bot
cp registration.yaml /tmp/registration.yaml.bak
git stash
git pull
cp /tmp/registration.yaml.bak registration.yaml
git stash pop
npm install
# Stop the current process (Ctrl+C), then:
npx ts-node bot.ts

Webhook examples

After generating a webhook link (via !webhook), you can send data to it with curl:

# Send plain text
curl -X POST http://localhost:3000/webhook/<token> -d 'Hello from webhook'

# Send JSON
curl -X POST http://localhost:3000/webhook/<token> \
  -H 'Content-Type: application/json' \
  -d '{"message":"hello"}'

# Send text plus an image (fetched from the given URL)
curl -X POST "http://localhost:3000/webhook/<token>?img=https://example.com/image.png" \
  -d 'optional caption text'