TellMe

A server and client notifications system written in Python that alerts you of events via SimpleX chat or Matrix.

Overview

TellMe monitors for events (completed processes, server uptime, etc.) and sends notifications through a built-in server to SimpleX chat or Matrix over websockets. Starting from version 2.2, TellMe supports GoAlert messages natively.

Client Features

Send messages: -m "Your message" - Send custom notifications
Monitor processes: -p <pid> - Wait for a process to exit, then notify
Watch commands: -w "command" - Run a command periodically and notify on output
Ping hosts: -P <host> - Monitor host availability until it's reachable

Server Setup

Installation

cd server/src
pip install -r requirements.txt

Configuration

Configure hooks in /etc/tellme/hooks.yml:

2345555XE:
  transport: "simplex"
  target: "#Bottest"

Supported transports: simplex, matrix

(Optional) Configure Matrix credentials in /etc/tellme/config.yml:

matrix_homeserver: "https://matrix.org"
matrix_access_token: "syt_your_token_here"
matrix_user_id: "@yourbot:matrix.org"

Obtaining a Matrix Access Token

Via Element Web (easiest):

Log into Element (https://app.element.io or your homeserver's Element instance)
Go to Settings (gear icon) → Help & About
Scroll to Access Token → click "Reveal Access Token" → copy it

Via Matrix API (curl):

curl -X POST "https://your-homeserver.url/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"@youruser:homeserver","password":"yourpassword"}'

The response includes access_token.

Important:

Use a dedicated bot account, not your personal one
Keep the token secure (don't commit to git)
Revoke it in Element settings if compromised

Run the SimpleX CLI chat as a daemon (for SimpleX transport).
Start the server:

python tellmesrv.py

Ansible

An example Ansible role is included in Ansible/tellme_notification for integrating TellMe notifications into Ansible playbooks.

Created by Taurix IT (https://www.taurix.net) | Licensed under AGPLv3+

2.2 KiB Raw Blame History