https://github.com/rondevhub/mastohashbot
MastoHashBot is a lightweight automation bot for Mastodon. It automatically searches for posts (toots) containing specific hashtags and boosts them. The bot ensures that no post is boosted twice by storing processed IDs in a JSON file and also cleans up old entries after a configurable period of time.
https://github.com/rondevhub/mastohashbot
fediverse fediverse-bot mastodon mastodon-bot opensource
Last synced: 2 months ago
JSON representation
MastoHashBot is a lightweight automation bot for Mastodon. It automatically searches for posts (toots) containing specific hashtags and boosts them. The bot ensures that no post is boosted twice by storing processed IDs in a JSON file and also cleans up old entries after a configurable period of time.
- Host: GitHub
- URL: https://github.com/rondevhub/mastohashbot
- Owner: RonDevHub
- License: mit
- Created: 2025-09-29T11:09:03.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-29T11:28:59.000Z (9 months ago)
- Last Synced: 2025-10-09T04:26:43.364Z (9 months ago)
- Topics: fediverse, fediverse-bot, mastodon, mastodon-bot, opensource
- Language: PHP
- Homepage:
- Size: 11.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 🤖 MastoHashBot
MastoHashBot is a lightweight automation bot for Mastodon.
It automatically searches for posts (toots) containing specific hashtags and boosts them.
The bot ensures that no post is boosted twice by storing processed IDs in a JSON file and also cleans up old entries after a configurable period of time.
[](https://www.buymeacoffee.com/RonDev)
[](https://ko-fi.com/U6U31EV2VS)
[](https://github.com/sponsors/RonDevHub)
[](https://www.paypal.com/paypalme/Depressionist1/4,99)
---
## ✨ Features
- 🔎 Searches for multiple hashtags across any Mastodon instance
- 🚀 Automatically boosts posts (no duplicates)
- 🧹 Cleans up old entries from the JSON file after `X` days
- 📂 Stores boosted IDs locally in `posted_ids.json`
- ⚙️ Configurable via environment variables or script variables
---
## 📋 Requirements
- PHP **>= 7.4** (for the PHP version of the bot)
- cURL extension enabled in PHP
- Bash + `curl` + `jq` (for the Bash version of the bot)
- A Mastodon **access token** with `write:accounts` and `write:statuses` permissions
- A Mastodon **instance URL** (e.g. `mastodon.social`)
---
## ⚙️ Setup
### 1. Get a Mastodon Access Token
1. Log in to your Mastodon instance
2. Go to **Preferences > Development > New Application**
3. Give it a name, e.g. `MastoHashBot`
4. Select required permissions:
- `read:statuses`
- `write:accounts`
- `write:statuses`
5. Copy the generated **Access Token**
---
### 2. Configure the Bot
Edit the script (PHP or Bash) and set:
```php
// PHP Version
$accessToken = 'INSERT_YOUR_ACCESS_TOKEN_HERE';
$instance = 'YOUR_INSTANCE_HERE';
$hashtags = ['hashtag1', 'hashtag2'];
$cleanupDays = 30;
```
```bash
# Bash Version
ACCESS_TOKEN="INSERT_YOUR_ACCESS_TOKEN_HERE"
INSTANCE="YOUR_INSTANCE_HERE"
HASHTAGS="hashtag1 hashtag2 hashtag3"
CLEANUP_DAYS=30
```
---
### 3. Run the Bot
PHP Version:
```
php mastohashbot.php
```
Bash Version:
```
bash mastohashbot.sh
```
You should see log messages like:
```
Starting Mastodon bot run...
There are 0 IDs that have already been boosted.
Searching for posts with hashtag #fediGive...
Post ID 123456 boosted successfully!
Bot run completed.
```
---
### 🗑 JSON File Cleanup
The bot stores boosted post IDs in a JSON file (`posted_ids.json`).
To prevent the file from growing indefinitely, entries older than `$cleanupDays` are automatically removed.
---
### 🤝 Usage in Production
- Run the bot regularly via cronjob or a systemd timer, for example:
```
# Run every 15 minutes
*/15 * * * * php /path/to/mastohashbot.php >> /path/to/mastohashbot.log 2>&1
```
- Monitor the logs (`mastohashbot.log`) to check the activity.
---
### 📦 Folder Structure
```
.
├── mastohashbot.php # PHP version of the bot
├── mastohashbot.sh # Bash version of the bot
├── posted_ids.json # Stores boosted IDs
└── README.md # Project documentation
```
---
### 🔒 Security Notes
- Keep your Access Token secret – it allows actions on your Mastodon account.
- Do not commit your token into version control (e.g. GitHub).
- Consider using environment variables or `.env` files instead of hardcoding tokens.
---
### 🌐 Example Use Cases
- 📢 Community hashtags (e.g. `#fediGive`, `#fediHelp`)
- 🛒 Local marketplaces (e.g. `#flohmarkt`)
- 🐘 Automated content boosting for niche topics
---
### 🛠 Troubleshooting
- Error: API request error (401 Unauthorized)
→ Check your access token and permissions
- Error: No results found
→ Make sure the hashtag exists and is used
- Error: JSON decode error
→ The Mastodon API returned unexpected data (try again later)
---
### 📜 License
MIT License – free to use, modify, and distribute.
---
### 👨💻 Author
Developed with ❤️ for the Fediverse.
Feel free to fork, contribute, or open issues!