vkrepost_to_tg/README.en.md

Portal in VK

Русский · English

A Telegram bot that forwards new posts from VK (VKontakte) pages and communities to Telegram: subscribe with /add <short name> and every new post arrives as a message, with photos, video covers, documents, audio, polls and reposts. The bot speaks Russian.

Status: personal project, completed · bot @vkportalbot

Stack: Python 3.12 · aiogram 3 · vk_api · SQLite · Docker

Features

• Up to 10 subscriptions per user: personal pages, groups and public pages
• A post is converted to Telegram format:
  • photos, video covers and image documents — as an album;
  • audio — as a separate message;
  • polls, links and documents — in the text;
  • [id1|Name] mentions — as links;
  • reposts show both authors and the comment.
• Telegram limits are handled: a single photo, albums up to 10 items, long text as separate messages
• /last_post — the latest post of any page; /update — resend a post with fresh data
• Your own VK token (optional) gives posts from closed pages you follow and likes from Telegram (/like as a reply to a post)

Important

If you send the bot your VK token, it is stored on the bot's server. Delete it with /logout; revoke access completely in VK settings, "Apps and websites".

Running

git clone https://github.com/EDeev/vkrepost_to_tg.git && cd vkrepost_to_tg
cp .env.example .env      # BOT_TOKEN and the VK app service key
docker compose up -d

Prebuilt image: docker pull ghcr.io/edeev/vkrepost_to_tg or docker pull dcr.deev.su/edeev/vkrepost_to_tg. The SQLite databases are created on first start.

Without Docker: Python 3.12, pip install -r requirements.txt, then cd code && BOT_TOKEN=… VK_SERVICE_TOKEN=… python bot.py.

How it works

code/bot.py          entry point and background polling of subscriptions every minute
code/handlers.py     commands: subscriptions, latest post, likes, VK token
code/vk_scripts.py   VK API requests and post parsing
code/scripts.py      post → HTML text and Telegram media, sending within Telegram limits
code/sql.py          users, subscriptions and each page's latest post (SQLite)

For a closed page the bot uses the token of one of its subscribers; for open pages, the service key. VK requests run in a separate thread so the bot never freezes. Text from VK is escaped.

Development

pip install -r requirements-dev.txt
ruff check --select E9,F code tests && pytest

The tests cover post parsing (escaping, mentions, links, reposts, album limit) and sending (single photo, long text, audio). The Docker image is built on v* tags and published to GitHub Packages and dcr.deev.su.

License

MIT — see LICENSE.

Author

Egor Deev — GitHub · Telegram · egor@deev.space

---

_{⭐ If you find this project useful, give it a star on GitHub!}

_{Made with ❤️ — deev.space}