# 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](# Features) .

## 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. 

* Installation JRE: `$ sudo apt-get install default-jre`
* 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](https://snapcraft.io/install/rustup/raspbian)
    * 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](https://github.com/AsamK/signal-cli/wiki/Provide-native-lib-for-libsignal) and [Libzkgroup](https://github.com/signalapp/zkgroup/releases). 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*.
* Installation of the Libzkgroup library
    * `$ make libzkgroup`
	You can optionally compile with four processor cores using the `-j4` parameter.

## Compilation and installation of the signal-cli
This section corresponds to the [signal-cli instructions](https://github.com/AsamK/signal-cli#building) 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
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](https://signalcaptchas.org/registration/generate.html)
    * 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](https://www.heise.de/select/ct/2021/14/2110907424679785321) serves as a basis, which in turn builds on the signal-cli's [system-bus guide](https://github.com/AsamK/signal-cli/wiki/DBus-service#system-bus). 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](https://www.deepl.com)

## 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](https://www.geschicktgendern.de)

`.freegames` -  Displays video games that are currently free, *but usually not*. Powered by [freegamesyo](https://www.freegamesyo.com) 

## 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](https://ejdus.de/einricht_gemeinden/jugendkirche/)

`.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>` - 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.