Random Chat Telegram Bot

This project's defining constraint is that the whole product lives inside a Telegram conversation. There's no separate UI for users. Onboarding, matching, chatting, and moderation all happen through bot messages, reply keyboards, and Telegram's native location and contact sharing. The bot is built in Node.js and TypeScript on node-telegram-bot-api, with Express and MongoDB behind it. New users move through a thirteen-step onboarding state machine that captures everything from name and age to gender preferences, location, and interests, persisting progress so a user who drops off resumes exactly where they left.

Matching is a weighted scoring function that combines geography (same city, country, or worldwide), shared interests, and age proximity, with mutual gender preference acting as a hard gate and blocked/skipped users excluded from the candidate pool. When two users match, they get a time-limited chat, and messages relay between them through Telegram's copyMessage primitive, so neither person sees the other's real identity unless they explicitly choose to share their profile. Skip, block, and report form a small state machine, with a report automatically blocking the other user and returning the reporter to the queue. The whole system is kept clean by a per-minute cron job that closes expired chats, deletes relayed messages after a retention window, and does all of this while respecting Telegram's rate limits, a minimum inter-call throttle, exponential backoff that honors the API's retry_after, and job locks that prevent overlapping cleanup runs. A React (MUI) admin panel handles users, reports, bans, and ad campaigns.