| .forgejo/workflows | ||
| admin-tools | ||
| code_review | ||
| data | ||
| docker | ||
| log | ||
| migrations | ||
| profile_graphics | ||
| resources | ||
| src | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| alembic.ini | ||
| CONFIGURATION.md | ||
| DEVELOPMENT.md | ||
| LICENSE.md | ||
| pyproject.toml | ||
| README.md | ||
| requirements-dev.txt | ||
| requirements.txt | ||
| TO_DO.md | ||
NotifyBot
NotifyBot watches Mastodon hashtags and DMs you when new posts appear, so you never miss the conversations that matter. It's best for niche or low-traffic hashtags — the ones that slip past your timeline.
Users interact with NotifyBot entirely through Mastodon direct messages — sending commands like subscribe cats to create hashtag subscriptions, and unsubscribe moose to remove them. When a new post appears with a subscribed hashtag, the bot sends a DM notification with a link to view recent posts.
Visit the live instance at: https://notifybot.jampdx.net
See the TO_DO.md file for current issues queue. See the LICENSE.md file for licensing information.
Getting Started
Requires Python 3.12 or later.
Environment
To set up the environment, run:
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/alembic upgrade head
Mastodon Account
The bot requires a Mastodon account to operate. Different Mastodon instances have different policies on running bots — check your instance's rules before setting up a bot account.
When setting up the account, enable the "This is a bot account" checkbox in the profile settings. This lets other users know they are interacting with an automated account.
Notification Filtering
On Mastodon 4.3 and later, the notification filtering policy must be configured for the bot account, or DMs from users may be silently held for review. To configure this:
- Log into the bot's Mastodon account in the web interface.
- Go to the Notifications page.
- Click the settings icon (vertical sliders) at the top right of the Notifications column to reveal the "Manage notifications from..." settings.
- Set "Unsolicited private mentions" to "Accept". If this is left at "Filter", the bot may miss a user's first DM after their follow request is accepted.
- Verify that "People you don't follow" is also set to "Accept", since the bot does not follow its users.
- Verify that "People not following you" is also set to "Accept", since newly-accepted followers may not yet be recognized as following the bot.
Access Token
You will need an API access token, so the bot can interact with Mastodon. To obtain an access token:
- Log into the Mastodon account where you will be running the bot.
- Go to Preferences → Development → New Application.
- Create a new application with scopes:
read,write,follow. - Copy the "Your access token" value.
See CONFIGURATION.md for where to store the access token and other settings.
Configuration
The bot is configured by TOML files in the resources/config/ directory.
See CONFIGURATION.md for full details.
There are a handful of settings marked CONFIGURE. They are the ones that likely will need to be to set for a new installation.
Execution
To launch the application in development mode:
.venv/bin/python3 src/__main__.py
For production, set the environment variable APP_ENV=prod. See CONFIGURATION.md for details.
Operations
Approving Follow Requests
The bot requires manual approval of new followers.
The bot will DM the accounts listed in bot.admins when a new follow request is received.
Log into the bot's Mastodon account and review the pending follow requests.
Posting Announcements
To broadcast a message to all subscribed users, post from the bot's Mastodon account using the hashtag configured in bot.announcement_hashtag.
Each subscriber will receive a DM with a link to the post.
It's good practice to include your personal user handle in the announcement, so you can see any replies.
User Messages
Users can send messages to the bot admin using the message command (e.g. message I like your bot.).
The bot will DM the accounts listed in bot.admins when a message is received.
Log into the bot's Mastodon account to respond to the message.
It's good practice to include your personal user handle in the message, so you can see any replies.
Troubleshooting
Users Not Receiving Responses
If a user reports that the bot is not responding to their DMs, check the bot's Mastodon account for notifications that are being held. If so, approve them, then review the notification filtering policy settings. See the Mastodon Account section for details.
Author
Courtney Rosenthal
email: cr@crosenthal.com
Mastodon: https://pdx.social/@courtney