Pingbot

Pingbot monitors a Mastodon account, and will ping one or more other accounts any time that account gets a notification. This is useful for monitoring an admin account that may not be logged in all the time, or for checking in on an old account after you’ve made a new one.

You cannot monitor an account you can’t log into. This is deliberate and will not be changed.

Setup

Pingbot requires the ananas package. You can install it with pip:

pip3 install ananas

Note that the version of ananas that’s currently available on pip (as of 4/28/22) is not compatible with Python 3.10. There’s already a PR in to fix that so we just have to wait for PyPI to catch up.

You can either download pingbot.py and sample-config.cfg directly, or you can go to the command line on the server you want to run Pingbot on and run

git clone https://git.noelle.codes/noelle/Pingbot.git

This will create a new directory called Pingbot that contains the repository’s files. You’ll run ananas (see below) from there.

In the Mastodon web interface on the account you want to monitor, open Preferences, then Development, and click the New Application button at the upper right.

You’ll need to give your application a name; this can be pretty much anything you want. Leave “Application website” blank, and leave “Redirect URI” alone.

You can leave Scopes alone; all Pingbot does is check your notifications and send you DMs. However, if you want to limit Pingbot’s access for security, it must have read:notifications and write:statuses in order to do its job.

Click the Submit button at the bottom, and you’ll see “Application successfully created”, as well as your new application in the list below. Click the name you chose (it should be blue), and this will bring up a screen that shows you the client key, client secret, and access token.

In Pingbot’s directory, copy sample-config.cfg to config.cfg, and then open it for editing. You’ll need a separate header in the config file, enclosed by [brackets], for each bot you want to run in the same directory. The sample configuration file includes a [pingbot] header for you, as well as a [DEFAULT] header for settings that apply to every bot in the directory. You should place most of your information under the [pingbot] header; the configuration file includes instructions on how to do this. (Note that what the Mastodon web interface calls a “Client key”, the config file calls a client_id.)

In the configuration file, every username you include should not have an @ before it (e.g. noelle@elekk.xyz, not @noelle@elekk.xyz).

Once all your information is in the configuration file, save it, and then run

ananas config.cfg

in a terminal window and your bot will start up and begin listening! In Linux, you can run your bot in the background by adding an & to the end:

ananas config.cfg &

Or you can use a window manager like tmux or screen, which will let you keep the bot running on a server without you havnig to be logged in.

Making configuration changes

If you want to change Pingbot’s settings, you’ll need to stop and restart the bot. Make sure you stop the bot before you make changes; Pingbot saves its configuration when it shuts down, and might overwrite your changes.

I need help!

You can contact me at my Mastodon account and I’ll do my best to help you out. :)

TODO

• On startup, make Pingbot get permission from all accounts it wants to notify (and store that permission so it doesn’t ask multiple times)
• Make Pingbot optionally not respond to replies from accounts in its notify list
• Internationalization