Matrix Stream Alerts

A small project to glue Matrix and Twitch together. All it does is post a message whenever a content creator goes live on Twitch, and redact the message once the creator goes offline.

Getting Started

You must configure the host environment and bot. Matrix Stream Alerts is not plug-and-play, so it'll be quite involved. The project may be challenging to set up for beginners to self-hosting, though it is still achievable with some dedication.

Every step will have concise instruction aimed at experienced users, followed by optional and very verbose guidance if you need a little more help. Expect to spend a bit of time reading up on topics if they are not known to you already.

1. Prerequisites

You must install the following software:

• Node.js v24 or later
• Git

💬 I recommend using a package manager like apt on Debian or winget on Windows.
🚧 In future there will be stable releases via Docker and npm. Until the v1.0.0 release, we'll only support a more developer centric installation method with Git.

2. Initialize Matrix Stream Alerts

You must download and install Matrix Stream Alerts.

git clone https://codeberg.org/SethFalco/matrix-stream-alerts.git
cd matrix-stream-alerts
corepack enable
yarn install
npm i -g .

Verify that the installation completed successfully by running:

matrix-stream-alerts --version

Next, you must initialize a config file which you'll have to populate before you can run the bot. Run the init command, short for initialize:

matrix-stream-alerts init

This will create a file in your current working directory named config.yml. This stores any settings and secrets the bot needs to run. The next few steps will work towards populating it.

3. Create the Matrix Bot

Create a new Matrix account for your bot. Once you've registered, specify the homeserver URL over the matrix.homeserverUrl value in config.yml file.

Next, you need to get an access token. You can do this with the bot-token command:

matrix-stream-alerts bot-token

It will ask you for your username and password, then print an access token with no expiration date. Copy the output and paste it over the matrix.accessToken value in config.yml.

❓ Need more help?

You need a Matrix account to actually post messages on Matrix. It's recommended to use a separate account from your personal one. Visit matrix.org to sign up for free or find a reputable third-party host to register with.

If you're not sure how to register and are not picky about where you want to register, account.matrix.org/register is a sensible choice.

4. Invite your Matrix Bot to a Room

On your Matrix client, create a room if required, then invite your Matrix bot to it. You do not have to manually accept the invitation from your bot account.

Matrix Stream Alerts logs in as your bot and automatically accepts room invitations that were sent by the administrator hosting this software—that's probably you.

Now is a good time to write your Matrix username in matrix.adminId, then find the ID of the room and paste it over the value of matrix.roomId. This completes the Matrix section.

5. Create a Twitch Application

You must also create a Twitch account if you don't have one already. Then register as a developer on the Twitch Developer Console.

Following this, navigate to Applications section and register a new application. Once registered, you'll get a Client ID and Client Secret. You need both of these! Take these values and past it over the values for twitch.clientId and twitch.clientSecret respectively.

❓ Need more help?

You need the Twitch API access to get information about Twitch users, which inherently requires a Twitch account. These credentials are also used by some helper commands, such as the one explained in the next section.

6. Subscribing to Streamers

Next, you must define which streamers you want to subscribe to. Find the twitch.users section, this is a list of users. Each streamer has the following properties:

• id: The Twitch ID of the streamer, not to be confused with a Twitch username.
• vocabulary: If they prefer masculine, feminine, or neuter (default) terms.

For English, the vocabulary property does nothing, but in some languages such as Bosnian, words will differ based on the gender of the streamer.

You probably don't know the ID of the streamers you want to subscribe to, so we'll need to convert the username to an ID. You can use the twitch-id command to do this:

matrix-stream-alerts twitch-id

This will ask for a username or display name, then writes the ID of the user. Let's assume the ID is 38977953. You must then add it as an entry to twitch.users:

twitch:
  users:
    - id: '38977953'
      vocabulary: 'masculine'

To add another streamer, do the command again and append it to the list. You may find it helpful to insert a comment above each user, so you can remember who each ID represents. Do so by putting a # symbol followed by whatever you want before each item in the list.

twitch:
  users:
    # JoeStone
    - id: '38977953'
      vocabulary: 'masculine'
    # Vukory
    - id: '496194872'
      vocabulary: 'feminine'

7. Register a Domain

If you don't already have one, register a domain with your registrar of choice.

❓ Need more help?

A domain is like a name or identifier for a website. For example, falco.fun, teaparty.diy, or vukory.art. You can get one by signing up to a registrar and purchasing a domain for a specific duration.

Registering a domain is technically optional but strongly recommended. Running Matrix Stream Alerts without a domain has not been tested and is not officially supported.

Twitch's EventSub API requires an HTTPS (not HTTP) endpoint to POST data to. So you'd be running a small website, and Twitch will post a message to it whenever a content creator has gone live or offline.

Enabling HTTPS requires an SSL/TLS certificate, which isn't common for IP addresses. Meanwhile, services like Let's Encrypt 🇺🇸 offer free and first-class support for issuing TLS certificates for domain names.

💡 Let's Encrypt is getting support for IP Certificate in late 2025.
⚠️ A domain name usually requires payment, have your wallet ready.
💬 I personally use and recommend Gandi 🇫🇷—alternatively you can find list of reputable registrars on ICANN's List of Accredited Registrars.

Configuration

The configuration for Matrix Stream Alerts is split across two locations. This is to enforce principle of least privilege.

TL;DR: Don't give the bot permission to do things you don't need it to do. Behavior that can be controlled through Matrix permissions should be managed through them.

Config File

Most options reside in a mandatory config file named config.yml. This must exist in the location you invoke matrix-stream-alerts from.

# Language to send messages in. Doesn't affect logs!
lang: 'en'
matrix:
  # Bot's homeserver.
  homeserverUrl: 'https://matrix.org'
  # Bot's access token. Get an access token with the command:
  # matrix-stream-alerts bot-token
  accessToken: '…'
  # Username of whoever's running this—presumably yours.
  adminId: '@username:homeserver.tld'
  # Room to post messages to.
  roomId: '!room:homeserver.tld'
twitch:
  # Twitch client ID.
  clientId: '…'
  # Twitch client secret.
  clientSecret: '…'
  users:
    - # Twitch user ID. Get a Twitch ID from username with the command:
      # matrix-stream-alerts twitch-id
      id: '38977953'
      # For languages with gendered vocabulary.
      # Possible values: masculine, feminine, neuter (default)
      vocabulary: 'masculine'
webserver:
  # Port to use for webserver.
  port: 3000
  # Domain for Twitch to post messages to. Must be publicly accessible.
  hostName: 'matrix-stream-alerts.domain.tld'
  # Random string. Must persist between sessions.
  secret: '…'

Permissions

Some settings are configured through Matrix permissions. These can be managed in the majority of Matrix clients—review your room settings.

No restart is necessary when changing permissions, the bot will immediately behave as documented as soon as changes are synced.

Permission	Description	Granted	Revoked
m.room.redaction	Redact messages authored by the bot itself. Not to be confused with the redact permission, which is to redact messages authored by others.	Once a stream goes offline, redacts the announcement.	Once a stream goes offline, edits the announcement to remove @room if it is present and append an update.
room	Mention everybody in the room using @room.	When a stream goes live, prefix the announcement with @room.	When a stream goes live, the announcement does not include @room.