Signalbot

This project realizes a signal community bot known from other social plattforms like Twitch, Discord & Mumble. It is based on the simple request to automatically remind a groupchat of upcoming birthdays and events.

Installation

This chapter covers the whole installation of the signalbot while using a Raspberry Pi 4 with RaspberryOS already installed. Additionally you'll need a phonenumber that is not linked to an existing signal account. If you just want to use the bot via Signal scroll down to Features. You can find any addiotional information in docs/main.pdf.

Installation preparation

This section describes how to install signal-cli on a Raspberry Pi 4. Note that earlier hardware versions are not supported due to the built-in processor generation. In order for libsignal to work you'll need JRE 17 or higher.

• Installation JRE: $ sudo apt-get install default-jre
• Installation cmake, clang & libclang: $ apt-get install clang libclang-dev cmake make
• Installation Gradle: $ sudo apt-get install gradle
• When installing Rust on a Raspberry Pi, it is recommended to install rustup - The Rust Language installer by snapcraft
  • Installation of the Snap Store: $ sudo apt install snapd
  • Restart the Pi: $ sudo reboot
  • Installation of core snap: $ sudo snap install core
  • Installation of rustup: $ sudo snap install rustup --classic
• Installation of the protocol buffer compiler: $ sudo apt install protobuf-compiler

Compilation of the signal-cli libraries

The signal-cli equires the libraries Libsignal-client and Libzkgroup. They will be downloaded from GitHub and then compiled.

• Installation of the Libsignal-client library
  • Switch to the java directory: $ cd java
  • Comment out the compilation of the Android Lib with #
  • $ sed -i "s/, ':android'//" settings.gradle
  • $ ./build_jni.sh desktop
    The compiled library is then located in the directory libsignal-client under target/release/libsignal_jni.so.

Compilation and installation of the signal-cli

This section corresponds to the signal-cli instructions for compiling.

• Download the Git-Repository: $ git clone https://github.com/AsamK/signal-cli.git
• compile with Gradle: $ ./gradlew build
• Create a shell wrapper in the directory build/install/signal-cli/bin: $ ./gradlew installDist
• Create the tar file in the build/distributions directory: $ ./gradlew distTar

The libraries compiled in the previous section must now be replaced in the compiled signal-cli tar.

• Switch to directory signal-cli/build/distributions
• unzip tar: $ sudo ln -sf /opt/signal-cli-"${VERSION}"/bin/signal-cli /usr/local/bin/
• delete libsignal-client from the jar in the /opt/signal-cli-*/lib folder: $ zip -d signal-client-java-*.jar libsignal_jni.so
• delete the library libzkgroup from the jar: $ zip -d zkgroup-java-*.jar libzkgroup.so
• Specify the path to the compiled libraries in /opt/signal-cli-*/bin/signal-cli:
  • JAVA_LIBRARY_PATH="-Djava.library.path=/your/java/library/path"
  • exec "$JAVACMD" "$JAVA_LIBRARY_PATH" "$@"

Installing the required Python libraries

Manually install the PyGObject: $ sudo apt install python3-gi Automatically install all required packages: $ pip3 install -r requirements.txt

Create an Account

A phone number is required to create an account. It is possible to receive the opening code via SMS or voice call. In these instructions, a landline number is used for the account and thus the activation by voice call. Please note that the country code must be entered for the telephone number, which is +49 for Germany.

• Register the phone number. USERNAME must be replaced by the phone number.
  • via SMS Verification: signal-cli -u USERNAME register
  • via Voice verification: signal-cli -u USERNAME register --voice
• If the registration fails with the error message Captcha invalid or required for verification, a CAPTCHA must be solved:
  • Visit the Signal CAPTCHA Website
  • solve the CAPTCHA
  • The token can be read out via the console of the web developer tools. In most common browsers, they can be called up via pressing F12. It should be noted that the website has no other content and is therefore completely empty. The token is the entire content after the redirect address: signalcaptcha://
  • Now the registration command from the first point is restarted with the additional parameter --captcha TOKEN.
• The code received by SMS or call is passed instead of CODE: signal-cli -u USERNAME verify CODE

Set up the Deamon

When setting up the Deamon service, an article of the c't 14/2021 serves as a basis, which in turn builds on the signal-cli's system-bus guide. The signal-cli is set up as a Systemd service, so that it is automatically started at system startup. In addition, the service is automatically restarted in the event of an error.

As described in c't and the signal-cli wiki, a separate user is set up for signal-cli. This is a common practice in order to simplify access rights. In addition, all users of the system have access to the running signal-cli session via the D-Bus.

The user signal-cli for the Deamon is created via the command
sudo adduser --system --home /var/lib/signal-cli signal-cli
The default config and service files are copied as root from the signal-cli directory with the following commands \

• sudo cp data/org.asamk.Signal.conf /etc/dbus-1/system.d/
• sudo cp data/org.asamk.Signal.service /usr/share/dbus-1/system-services/

The service file is stored under /etc/system/system/signal-cli.service. To save the file there, root privileges are also required. With the entry \ExecStart=/usr/local/bin/signal-cli --config /var/lib/signal-cli -u USERNAME daemon --system the command for the program call is specified. USERNAME has to be replaced again.

The created account data is stored in the home directory of the signal-cli user. The command sudo cp -r ~/.local/share/signal-cli* /var/lib/signal-cli copies all files from the personal directory. Finally sudo chown -R signal-cli /var/lib/signal-cli is used to set that all files in the created home directory belong to the user with the same name.

The service is activated with the command sudo sytemctl --now enable signal-cli and started with sudo systemctl start signal-cli. With the command sudo systemctl status signal-cli.service you can check if the setup was successful and if the service is active.

Features

The signalbot listens to commands that start with a dot. It offers a variety of features (or at least feature-ideas/request) that can be devided into following categories:

Static Texts

.help <command> - Get a list of all available commands. You can use the optional parameter to see details to a specific command.

.credits - Made with ☕ and ❤️

.remusFeinste - Get a recipe for sangria

.links - Get a list of all important links for various signal groups and community discords

Echos

A simple answer by the bot.

You can use:
.echo .ping .foo .hello .answer .marco .pisch .schwirbel and many more.

APIs

.yesno or .yn - Replies with a GIF and an answer that is either "yes" or "no"

.dadjoke - Make a really good pun

.deepl <LC>, <String> - Translate a word, sentence or even small texts with the DeepL translator. <LC> is a language code.
The bot will try to guess the language of <String>. Example: .deepl ES, Where is the library? Powered by DeepL

.addSong <Message> - Just add .addSong tou your normal Spotify Song Message. The bot will do the rest.

Crawlers

.genderneutral <German String> or .gn <German String> - Looks if a string (can be more than one sentence) is genderneutral and displays alternatives for genderspecific words. Powered by geschicktgendern

.freegames - DISCONTINUED: Displays video games that are currently free, but usually not. Powered by freegamesyo

Databases

.saveQuote <"Quote">; <Person>; <Year> - Save a quote. Example: .savequote "640 kB ought to be enough for anybody."; Not Gates; 1981

.randomQuote - Display a random quote.

.saveEvent <Headline>; <Date>; <Description> - Save an event. The bot will remind you one day before the event and at the actual day, each at 9 o'clock. Example: .saveEvent CSD-Düsseldorf; 16.10.2021; 🏳️‍🌈 🏳️‍🌈 🏳️‍🌈.

.nextEvent - Display the upcoming event.

.saveBirthday <Name>, <Date> - Save a birthday. The bot will congratulate on that day.

.nextBirthday - Display the next birthday.

.allBirthdays - Get a list of all birthdays.

Hint: instead of save, you can also write create and add!
To delete Quotes, Birthdays or Events please use .request

Misc

.tex <equation> - Convert a typed equation into a rendered formular.

.sips - A simple drinking game. Hand out a number of sips. But be aware of backfiring.

.trueamerican - The famous drinking game from New Girl. It is a bit messy, but you will become a TRUE AMERICAN!

.challenge - Bored? Stuck in your own comfort-zone? Get a random challenge for the day! In cooperation with Jugendkirche Düsseldorf

.roll <X-Y> - Roll a number n in a set range X <= n < Y. If no range is stated it will generate an integer in the interval 1 <= n < 100. Example: .roll 3-7

.request <String> or .req <String> - Do you wish for anything else? Request it!

Licence

This Signalbot is Free Software (Open Source) under the GNU Affero General Public License (AGPL) , either version 3 of the licence, or, at your option, any later version. In short this means:

You are free to run the software, for any purpose.

You are free to study how the software works and to adopt it to your needs. To make this possible, you have, as a user of the software, the right to obtain its source code, even if the software runs on a server, and you only connect to that server. (This “even on a server” clause is what distinguishes the GNU Affero GPL from the “normal” GNU GNU GPL.)

You are free to redistribute copies of this software, gratis or for a fee, provided that you don't deny anyone the rights we gave to you. (This “provided that” clause is the Copyleft principle, an essential feature of the GNU licences.)

You are free to improve this software and to redistribute your improvements, so everyone can benefit from them. Again, you may do this as a charity service, but you are also free to found a business providing this kind of service.

There is NO WARRANTY, unless you are paying someone to provide a warranty for you.