Skip to content

Latest commit

 

History

History
120 lines (82 loc) · 5.03 KB

README.md

File metadata and controls

120 lines (82 loc) · 5.03 KB

Kotlin GitHub code size in bytes GitHub last commit GitHub pre-commit ktlint Java CI with Maven

Notification Bot (Kotlin)

Telegram Bot for receiving notifications (Kotlin version).

Description

I created this simple Telegram bot for two reasons: first, make practice with the Kotlin programming language, that I'm starting to learn; second, find a way to receive system notifications (backups, package updates, etc...) from the small server I installed on a Raspberry Pi at home. It's very simple, but I plan to add more features if needed.

This program listens for messages on a UNIX-domain socket, parses them and sends them to a given Telegram group.

Prerequisites

First you need to create a bot with BotFather (see here) and get the authorization token, then add the bot to a group and retrieve its chat ID (you can see how to do it here).

To build the bot, you need Apache Maven correctly installed and configured.

The bot runs on Linux on JRE 1.8 or later, so make sure it is installed on your target system.

Installation

After cloning the repository, go to the project directory and run:

mvn package

When the build process is completed, copy the file target/notification-bot-<version>-jar-with-dependencies.jar to a directory of your choice and create a configuration file.

Configuration

The program needs a configuration file in JSON format to run. The default location is config.json in the program directory, but it can be changed via the --config/-c option.

The file format is the following:

{
  "socket_path": "/path/to/socket",
  "token": "AUTHORIZATION_TOKEN",
  "chat_id": -123456789
}
  • socket_path is optional, and contains the path to the UNIX-domain socket used for receiving messages. The default value is /var/tmp/notificationbot.sock.
  • token is the bot authorization token received by BotFather.
  • chat_id is the numeric chat ID of the group the bot sends notifications to.

Make sure to change the config file permissions in order to make it visible only to its user (e.g. r--------), since it contains your authorization token in plain text.

Usage

To start the program, run the following command:

java -jar notification-bot-<version>-jar-with-dependencies.jar

You might also want to run it as a service and start it at system boot.

Upon start, the program creates the socket at the specified location; you can send a string to it, for example using the Netcat utility:

echo -n "My notification message" | nc -U /path/to/socket

The socket will be deleted when terminating the program.

Message format

You can send both formatted text, using the HTML markup, and emojis, either using their HTML code or their alias (see here for the complete list, they are likely the same used in the GitHub Markdown). For example, the following string:

&#9888; <i>Warning!</i> I found a :bug: in the code!

is rendered in Telegram as follows:

⚠ Warning! I found a 🐛 in the code!

Commands

You can issue the following commands to the bot:

  • /serviceStop stop the service listening on the notification socket.
  • /serviceStart start the service listening on the notification socket.
  • /serviceInfo print the status of the service that listens on the notification socket.
  • /help print this command list.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/vonvikken/Notification-Bot-Kotlin. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Code of Conduct

Everyone interacting in the Notification Bot project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

License

This project is distributed under MIT license.