PastKing/tgbot-verify: A Python Telegram Bot for Automating SheerID Student and Teacher Verification

What tgbot-verify Automates and Who It Is For

SheerID is a third-party identity verification platform used by companies like Spotify, Google, and Bolt.new to confirm that users qualify for student or teacher discounts. The manual process requires visiting the service's verification page, filling in personal information, and uploading a verification document. tgbot-verify automates that process: a user sends a Telegram command with the verification URL, and the bot uses Playwright to drive a Chromium browser through the submission flow, generating the required identity information and documents automatically.

The five currently supported verification flows are Gemini One Pro teacher verification via /verify, ChatGPT Teacher K12 via /verify2, Spotify Student via /verify3, Bolt.new Teacher via /verify4, and YouTube Premium Student via /verify5, though the README marks /verify5 as still in development. The project is described as an improvement on an older codebase originally by GGBond from the @auto_sheerid_bot Telegram account.

The intended audience is technically capable individuals who want to run their own automated verification service, either for personal use or to operate a bot that other users connect to through Telegram. The credits system suggests the latter: users earn credits through daily check-ins and invites and spend one credit per verification.

Architecture: Telegram Bot, MySQL, and Playwright

The stack is Python 3.11 or later with python-telegram-bot 20.0 or later as the bot framework. Playwright 1.48.0 drives a headless Chromium browser for the verification submissions. MySQL 5.7 or later stores user accounts, credit balances, invite chains, and card-key records. Pillow and reportlab generate the PNG images of student and teacher cards that the bot submits as verification documents. The python-dotenv library reads configuration from a .env file.

The repository is organized around one Python module per supported service. The one/ directory handles Gemini One Pro, k12/ handles ChatGPT K12, spotify/ handles Spotify, youtube/ handles YouTube Premium, and Boltnew/ handles Bolt.new. Each module has its own config.py that holds the programId for that service's SheerID program. The central config.py at the repository root holds the credit costs and reward values:

VERIFY_COST = 1
CHECKIN_REWARD = 1
INVITE_REWARD = 2
REGISTER_REWARD = 1

The handlers/ directory separates user commands, admin commands, and verification commands into three files. The bot.py file is the entry point.

Setting Up and Running tgbot-verify

Clone the repository and install dependencies, then install the Chromium browser that Playwright will control:

git clone https://github.com/PastKing/tgbot-verify.git
cd tgbot-verify

pip install -r requirements.txt
playwright install chromium

Copy the env.example file to .env and fill in the required values. The mandatory variables are BOT_TOKEN (your Telegram bot token), ADMIN_USER_ID (your Telegram user ID), MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, and MYSQL_DATABASE:

BOT_TOKEN=your_bot_token_here
CHANNEL_USERNAME=your_channel
CHANNEL_URL=https://t.me/your_channel
ADMIN_USER_ID=your_admin_id
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=tgbot_verify

Start the bot with:

python bot.py

Docker Compose is also available. After copying and editing .env, run:

docker-compose up -d

The docker-compose.yml sets the container timezone to Asia/Shanghai and mounts a logs/ volume for log persistence. The Dockerfile installs all system-level Chromium dependencies that Playwright requires in the Linux environment.

Using the Verification Flow and the programId Dependency

Once running, a user starts a verification by visiting the target service's SheerID page, beginning the verification flow, and copying the full URL from the browser's address bar. That URL contains a verificationId query parameter. The user sends it to the bot:

/verify3 https://services.sheerid.com/verify/xxx/?verificationId=yyy

The bot takes the URL, drives Playwright through the remaining SheerID steps, and typically completes within a few minutes. If a verification fails repeatedly, the README states that the most common cause is an expired programId. Each service's SheerID program has a programId that can change; when it does, the bot's module config must be updated manually. The update procedure requires opening the target service's verification page, watching network requests in the browser developer tools for a call to services.sheerid.com/rest/v2/verification/, extracting the programId from that request, and updating the corresponding module's config.py file. The files to update are one/config.py, k12/config.py, spotify/config.py, youtube/config.py, and Boltnew/config.py.

Admin Commands and the Credits System

The credits system gates access to verifications. New users receive one credit on registration (REGISTER_REWARD = 1) and can earn one credit per daily check-in via /qd. Each invited user who registers gives the inviter two credits (INVITE_REWARD = 2). Administrators can also issue card keys redeemable for credits via /genkey, specify how many times a key can be used, and set an expiry period in days.

Administrator commands give the operator full control over the user base. /addbalance adjusts a specific user's credit balance. /block and /white add and remove users from a blocklist. /blacklist displays the current blocklist. /broadcast sends a message to all users. The admin user is identified by the ADMIN_USER_ID environment variable set at startup.

The credits model means a malicious or aggressive user cannot run unlimited verifications without earning or purchasing credits. However, the system also means that a fresh deployment with no users and no card keys has limited utility until credits are distributed manually or earned through the invite chain.

Maintenance Status, Limitations, and License

The last push to the repository was on 2026-03-12, which is more than six months before 2026-09-28. There are no recent commits. The README explicitly warns that programId values may expire at any time without notice, so a deployment that is not actively monitored will silently fail verifications when SheerID updates its programs. This maintenance burden is the largest practical concern with using tgbot-verify.

The project requires Python 3.11, a running MySQL instance, and a Playwright-compatible Chromium installation. This is a heavier stack than a typical Telegram bot, and the Dockerfile reflects that: it installs a long list of system-level graphics and browser libraries as part of the build.

A direct comparison tool is Selenium-based scrapers or Puppeteer scripts that automate the same SheerID flows without the Telegram interface. Those approaches give more programmatic control and remove the Telegram dependency, but they require building a user interface separately and lack the built-in credits and admin system. tgbot-verify's value is that all those pieces are already wired together.

The project is released under the MIT license, which permits modification and redistribution. The README adds a community-level requirement: derivative projects should remain open-source and retain the original repository link and author attribution.

Editorial conclusion

tgbot-verify is useful to developers who want to study how Playwright-based browser automation integrates with a Telegram bot framework and a MySQL-backed credits system. Running it in production requires maintaining a MySQL database, keeping the programId values in each module's config.py current as SheerID updates its programs, and installing a Chromium browser through Playwright. The last push was on 2026-03-12, which is more than six months before 2026-09-28, so there are no recent updates. Anyone deploying this should audit the programId values before use, since the README explicitly warns that they expire and cause silent failures.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. PastKing/tgbot-verify on GitHub
4. README