read_wine_bot

🍷 read_wine_bot

@read_wine_bot is a Telegram bot that runs giveaways on channel posts. It was built for the @read_wine channel and works in any channel that adds it as an admin.

[!WARNING] The hosted @read_wine_bot has no guarantees. It can stop, lose data or change at any time. For your own channel, host it yourself with your own bot token.

✨ What it does

• 🎟️ Join button. Adds a join button under a channel post and collects participants.
• 🎲 Random draw. Draws winners at random when the giveaway ends.
• 🔍 Review before publishing. Channel admins see which channels each winner is subscribed to, and can replace a winner. Then they publish the results under the post, or close the giveaway without results.

🔄 How a giveaway works

flowchart LR
    A["📨 Admin forwards a post<br/>to the bot"] --> B["⚙️ Setup<br/>end time, winners, button text"]
    B --> C["🎟️ Join button<br/>appears under the post"]
    C --> D["👆 Subscribers tap<br/>to join"]
    D --> E["⏰ End time:<br/>random draw"]
    E --> F["🔍 Admins review<br/>and replace winners"]
    F --> G["📣 Publish results<br/>under the post"]
    F --> H["🤫 Or close<br/>without publishing"]

👥 Who uses the bot

🔐 Permissions to grant

[!IMPORTANT] Grant only the permissions listed here and disable every other toggle. The bot never asks for more.

📢 Channel that runs giveaways

Open t.me/read_wine_bot?startchannel&admin=post_messages+edit_messages and select your channel. Telegram then adds the bot as an admin with the two permissions below already enabled. For your own bot, put its username in the link.

You can also go to Administrators → Add Admin → @read_wine_bot in the channel. Telegram enables the same two permissions there by default. Make sure that these permissions are enabled:

When an admin starts a giveaway, the bot checks both permissions. If one permission is missing, the bot stops the setup.

As an admin, the bot can also check winner subscriptions. Telegram does not give them to bots that are not admins.

🤝 Giveaway partner

A partner's channel needs no permissions at all. Open t.me/read_wine_bot?startchannel&admin=manage_chat and select your channel. Telegram requires at least one permission in this link. The link asks for manage_chat, which every admin has anyway. Then make sure that every other toggle is disabled. Telegram answers "is this user subscribed?" only to a channel's admins. That status is the only thing the bot needs from you.

With no permissions, the bot cannot post, edit, delete or ban anything in your channel. It also cannot run giveaways there, because giveaways need the Edit messages of others permission.

[!NOTE] Your channel appears in the results review of every giveaway the bot runs, in every channel. The review lists each winner's subscriptions to it. Admins of other channels see these subscriptions.

To end a partnership, remove the bot from your admins. The bot then stops checking your channel immediately.

🗄️ What the bot stores

The bot keeps its data in its own PostgreSQL database:

🚀 Run your own

You need:

• 🐘 a PostgreSQL database (tested with PostgreSQL 18). The bot creates its tables on the first start.
• 🔑 a bot token from @BotFather.

Then, on Windows, macOS or Linux:

1. Download the zip for your system from Releases. The name holds the system (windows, macos or linux) and the processor (amd64 for Intel and AMD, arm64 for ARM and Apple Silicon).
2. Extract the zip to a folder.
3. In that folder, copy .env.example to .env.
4. In .env, set the values that .env.example describes.
5. Open a terminal in that folder and run the bot: .\read_wine_bot.exe on Windows, ./read_wine_bot on macOS and Linux.

[!IMPORTANT] Start the bot from the folder that holds .env. It reads .env from the current directory and its parents, not from next to the binary. You can also use environment variables. They override the values in the file.

Before it starts, the bot checks every setting, the database and the token. If a check fails, the bot stops with an error that names the problem.

[!TIP] If the system blocks the downloaded binary, unblock it once: Unblock-File .\read_wine_bot.exe in PowerShell on Windows, xattr -d com.apple.quarantine read_wine_bot on macOS.

🐹 With go install

If you have Go 1.27 or newer, you can install the bot with one command instead of the download:

go install github.com/alexander-danilenko/read_wine_bot@latest

Go puts the binary in $(go env GOPATH)/bin. This method does not install .env.example. Create .env with the keys from .env.example, then run read_wine_bot from the folder that holds .env.

🧭 Where to read next

📄 License

MIT