goyban
a35abb0541
Completes TODO #5. Forwarding a post now asks whether to save it whole or extract its media; sending media directly is unchanged. Built on forwarding rather than copying file_ids. The bot already has the post in its private chat with the owner, so it stores message ids and forwards them back. forwardMessages takes a list and keeps an album intact, which is what made the caption-plus-album case tractable; ids must be strictly ascending, so they are sorted on the way out. - Vault rows live in their own table and every query is scoped to an owner_id, so a guessed id cannot reach someone else's saved post. Nothing in the vault is searchable inline, moderated or federated, and the separate table makes that structural rather than a flag. - Albums arrive as separate messages with no completion signal, so they are buffered by media_group_id behind a 1s debounce and prompt once. - The add path now takes a list of items, so extracting an album stores every piece under one set of keywords instead of asking repeatedly. - /vault searches keywords and the original caption, since the point of a vault is finding something you never got round to tagging. - Retrieval failures are reported: a message id is a pointer into the chat, not a self-contained file_id, so clearing history breaks it. Three near-identical keyword collectors are now one helper. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
126 lines
5.7 KiB
Markdown
126 lines
5.7 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 |
|
|
| `/vault [search]` | Retrieve a whole post you saved |
|
|
| `/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 |
|
|
|
|
### The vault — saving whole posts
|
|
|
|
Send the bot media directly and it behaves as it always has: it extracts the media and asks for keywords.
|
|
|
|
**Forward** a post to it instead and it asks what you want:
|
|
|
|
- **Save whole post** — keeps the post intact in your vault, caption and all. An album stays an album.
|
|
- **Extract media** — the existing behaviour, adding the media to your searchable library.
|
|
|
|
Retrieve saved posts with `/vault [search]`, which matches your keywords and the original caption. Each result has a button to forward it back to you, and one to remove it.
|
|
|
|
> **Vault posts only come back inside this bot.** Telegram's inline mode cannot forward an existing message, so `@yourbotusername keyword` does not reach the vault. Retrieve the post in the bot chat, then forward it wherever you want.
|
|
|
|
The vault is per-user and private: it is stored separately from the meme library, every lookup is scoped to its owner, and nothing in it is ever moderated or shared.
|
|
|
|
Saving stores a pointer to the message in your chat with the bot rather than a copy of the media. If you clear your chat history with the bot, saved posts can no longer be retrieved — the bot tells you when that happens so you can forward them again.
|
|
|
|
### 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`
|