# 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) |
| `/share [search]` | Mark a meme as shared or private (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.

### Sharing (groundwork)

Every meme is **private** by default. `/share [search]` lists your memes with 🔒 or 🌐 and lets you flip one. `/list` shows the same markers.

> **Nothing is shared yet.** This only records your intent. Federation — where independently run bots pool their shared memes — is not built, and no meme leaves this bot until it is. The wording in the confirmation describes what sharing *will* mean, because once a hub exists it is too late to start warning.

Two rules are enforced in the one query that will ever feed a hub: only **approved** and **public** media is eligible. Media awaiting moderation cannot be marked shared at all, and vault posts are in a separate table with no path there whatsoever.

Un-sharing stops future copies but cannot recall copies already taken, which is why the confirmation asks before making something public rather than after.

### Moving to another server

The only files you need to transfer are:

- `.env`
- `bot_db/media.db`