goyban
82b5da41b8
Completes TODO #2. PUBLIC_MODE swaps the ALLOWED_USERS allowlist for a membership check against REQUIRED_CHATS, with REQUIRE_MODE choosing between needing every chat or just one. - Stop is_admin() falling back to "everyone is an admin" when ADMIN_USERS is unset once PUBLIC_MODE is on. That fallback is the original single-owner convenience, but under public mode it handed moderation, /edit and /delete to anyone who found the bot. Public mode now grants admin to nobody until ADMIN_USERS is set, and says so at startup. Private deployments are unaffected. - Cache membership answers: inline search queries on every keystroke, so an uncached check meant several API calls per typed character. Grants last five minutes, refusals thirty seconds, so a user who has just joined is not locked out for the full window. - Fail closed when the membership check errors, and validate REQUIRED_CHATS at startup so a chat the bot cannot read is reported rather than silently refusing every user. - Refused users get a join prompt with real links instead of silence; inline shows a tappable bar that opens the bot and explains why. A private bot stays silent as before. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
108 lines
4.4 KiB
Markdown
108 lines
4.4 KiB
Markdown
# Memes Bot
|
|
|
|
A personal Telegram inline bot to store and search media (photos, GIFs, videos, voice, music, stickers, files) by keywords.
|
|
|
|
[فارسی](README.fa.md)
|
|
|
|
---
|
|
|
|
### Requirements
|
|
|
|
- A server with [Docker](https://docs.docker.com/engine/install/) installed
|
|
- A Telegram bot token from [@BotFather](https://t.me/BotFather)
|
|
|
|
### Setup
|
|
|
|
**1. Create the bot in BotFather**
|
|
- `/newbot` → get your token
|
|
- `/setinline` → enable inline mode, set a placeholder (e.g. `Search memes...`)
|
|
|
|
**2. Find your Telegram user ID**
|
|
|
|
You need your numeric Telegram user ID to whitelist yourself.
|
|
|
|
- **Easiest:** forward any message to [@userinfobot](https://t.me/userinfobot) — it replies with your ID
|
|
- **Alternative:** open Telegram Web, click your profile, the number in the URL is your ID
|
|
- **For multiple users:** repeat for each person and separate IDs with commas
|
|
|
|
**3. Clone and configure**
|
|
|
|
```bash
|
|
git clone https://git.goyban.com/goyban/memes_bot
|
|
cd memes_bot
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env`:
|
|
|
|
```env
|
|
BOT_TOKEN=your_telegram_bot_token_here
|
|
ALLOWED_USERS=123456789,987654321
|
|
```
|
|
|
|
**4. Run**
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
The database will be saved in `./bot_db/media.db`.
|
|
|
|
### Usage
|
|
|
|
**Adding media** — send the bot a photo, GIF, video, voice message, music file, sticker, or any document, then type keywords when prompted (comma-separated or one per message), then `/done`.
|
|
|
|
Round video messages are stored as regular videos: Telegram has no inline result type for video notes, so keeping them as video is what makes them searchable.
|
|
|
|
**Searching inline** — in any chat type `@yourbotusername keyword` to search and send.
|
|
|
|
Telegram suggests these commands as you type `/`, with a short description beside each suggestion.
|
|
|
|
**Commands**
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `/start` | Start the bot and show usage instructions |
|
|
| `/menu` | Show the available commands |
|
|
| `/list` | Show all saved media |
|
|
| `/review` | Review pending submissions one by one (admin only) |
|
|
| `/edit [search]` | Select a meme and edit its keywords (admin only) |
|
|
| `/delete <id>` | Remove an entry (get ID from `/list`; admin only) |
|
|
| `/cancel` | Cancel current add operation |
|
|
|
|
### Making the bot public
|
|
|
|
Set `PUBLIC_MODE=true` to open the bot to anyone who meets a membership requirement, instead of the `ALLOWED_USERS` list:
|
|
|
|
```env
|
|
PUBLIC_MODE=true
|
|
ADMIN_USERS=123456789
|
|
REQUIRED_CHATS=@mychannel,@mygroup
|
|
REQUIRE_MODE=all
|
|
```
|
|
|
|
`REQUIRED_CHATS` accepts `@username` or numeric ids. **The bot must be an admin in each one**, otherwise it cannot check membership and everyone is refused. The bot verifies this at startup and logs an error naming any chat it cannot read. `REQUIRE_MODE=all` demands every chat; `any` accepts one. With `REQUIRED_CHATS` empty the bot is open to everyone.
|
|
|
|
Users who don't qualify get a message listing what to join. In inline search they see a tappable bar that opens the bot and explains the same thing, rather than empty results with no reason given.
|
|
|
|
> **Set `ADMIN_USERS` before turning this on.** With no `ADMIN_USERS`, a private bot treats its users as admins — convenient for a one-person bot, but in public mode that would mean everyone. Public mode therefore grants admin to nobody until `ADMIN_USERS` is set, and logs an error at startup if you forget.
|
|
|
|
Membership answers are cached for five minutes, since inline search would otherwise query Telegram on every keystroke. Refusals are cached for only thirty seconds, so a user who has just joined gets in almost immediately.
|
|
|
|
### Accepting submissions
|
|
|
|
Set `ACCEPT_SUBMISSIONS=true` in `.env` to let non-admin users send media too. Their submissions are stored but stay invisible — they don't appear in inline search or `/list` until a moderator approves them. Admins' own media is still saved directly.
|
|
|
|
Run `/review` to work through the queue. Each item is shown with its keywords and four buttons: approve, reject, fix keywords, or stop.
|
|
|
|
The queue keeps no cursor. `/review` always fetches the oldest pending item, so you can stop after three and come back tomorrow, and several moderators can review at the same time without stepping on each other — if two open the same item, the first decision wins and the second is told it was already handled.
|
|
|
|
> **Leave this off unless you mean it.** With `ALLOWED_USERS` empty, everyone is an allowed user, so turning submissions on would accept media from anyone who finds the bot.
|
|
|
|
### Moving to another server
|
|
|
|
The only files you need to transfer are:
|
|
|
|
- `.env`
|
|
- `bot_db/media.db`
|