Whisper

Anonymous one-on-one stranger chat, inside Telegram.

Whisper is a self-hosted Telegram bot for Omegle-style anonymous chat. Two people press one button, get matched in seconds, and talk — with no names, no usernames, and no way to find each other afterwards. Every piece of infrastructure you need is in this repository: the bot, the matchmaking engine, the moderation layer, the database schema, the migrations, and the deployment stack.

It is a complete rewrite of the original single-file bot, rebuilt for real production traffic: atomic matchmaking under concurrency, proper rate limiting, abuse handling, and a privacy model that stores no message content at all.

• Demo
• Features
• Architecture
• Privacy model
• Quickstart
• Configuration
• Commands
• How it works
• Testing
• Deployment & operations
• Contributing
• Security
• Roadmap
• License
• Credits

Coming soon. A ~30 second capture of two accounts being matched, exchanging a message and a photo, then leaving with /next.

Live instance: Telegram: @your_whisper_bot

flowchart LR
    A["User A<br/>(Telegram client)"] -->|Update| B
    C["User B<br/>(Telegram client)"] -->|Update| B
    B["Whisper<br/>aiogram 3 dispatcher<br/>middlewares: DI · DB · ban"]
    B -->|"queue · sessions · rate limits<br/>atomic Lua matchmaking"| R[("Redis 7")]
    B -->|"metadata only<br/>users · reports · bans · stats"| P[("PostgreSQL 16")]
    B -->|"relayed messages"| T["Telegram Bot API"]
    R -.->|"TTL expiry"| B

• Redis is the hot path: the matchmaking queue, live sessions, rate-limit counters and block lists. The match claim runs inside a Lua script, so pairing is atomic across every bot replica.
• PostgreSQL is the durable path and holds metadata only. Message content is never written, logged, or queued anywhere.
• The bot is stateless between requests, so it can be scaled horizontally behind a single Redis instance.

Whisper's design goal is that a conversation is ephemeral by construction, not by policy.

1. No conversation content is ever stored. The relay forwards a message to the partner and forgets it. No message body, caption, filename, or media is written to PostgreSQL, Redis, or the logs.
2. Identity is stored, conversations are not. The bot records your Telegram ID, username, display name and language code, plus a match counter and activity timestamps — needed for abuse handling. None of it is ever linked to what was said: that link is never created.
3. Short-lived partner links. A live chat is two numeric IDs in a Redis session with a TTL, so it expires on its own. A report stores the reporter's ID, the reported ID, and the free-text reason the reporter typed.
4. No discovery. A partner can never learn who you are, and you cannot find a partner again once the session ends. /block makes that explicit and permanent.
5. Transparency for users. /privacy and /rules state what is stored and why, in the bot itself.

git clone https://github.com/mramitdas/Whisper.git
cd whisper
cp .env.example .env          # set BOT_TOKEN and OWNER_ID
docker compose up -d --build
docker compose logs -f whisper

Get a token from @BotFather; OWNER_ID is your numeric Telegram user ID. The stack brings up the bot, Redis and PostgreSQL with healthchecks — no other services required. The container applies pending database migrations on start, so there is no separate migration step.

Requires Python 3.12+ and a reachable Redis and PostgreSQL.

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

export BOT_TOKEN=...        # or put them in .env
export OWNER_ID=...
alembic upgrade head
python -m whisper.main      # or: whisper

whisper                              # console script
python -m whisper.main               # equivalent
docker compose up -d whisper         # containerised

All configuration is environment-driven (.env or your orchestrator). Every variable has a working default except the two marked as required.

FORBIDDEN_WORDS is parsed by a custom validator, so both FORBIDDEN_WORDS=spam,scam and FORBIDDEN_WORDS=["spam","scam"] work.

Matching. A user joining the queue is pushed onto a Redis sorted set scored by join time. Matchmaking runs as a single Lua script: it pops the oldest waiting user, creates a session with a TTL, and returns the pairing. Because the whole operation is atomic, two users can never be handed to the same partner, and a bot crash mid-match cannot leave a half-created session.

Sessions. A live chat is two user IDs plus a small metadata blob in Redis with SESSION_TTL_SEC. The bot keeps no state in memory, so restarts and deploys are transparent to users.

Moderation. Every outgoing message passes through the moderation filter (links, @usernames, forbidden words) and a sliding-window rate limiter before it is relayed. Reports are counted per unique reporter; crossing MAX_REPORTS_BAN applies an automatic ban, tears down the reported user's live session, and notifies their partner that the chat ended.

Idle sweep. A background task closes conversations that have been silent for longer than IDLE_TIMEOUT_SEC and notifies both sides.

pytest           # 58 unit/integration tests
ruff check .     # linting
mypy whisper     # type checking

The test suite needs no external services — Redis is emulated with fakeredis (including Lua execution) and the database with in-memory SQLite. CI runs the same three gates on every push and pull request.

Full E2E requires a real bot token and two Telegram accounts. Verify:

• /start, /help, /rules, /privacy respond correctly
• /search with no partner times out after MATCH_TIMEOUT_SEC and offers a retry
• Two accounts searching simultaneously are matched
• Text and every media type relay in both directions
• /next re-queues and re-matches; /stop notifies the partner
• Rapid messages trip the flood control
• Links and @usernames are blocked
• /block prevents future matches
• /admin_stats, /admin_ban, /admin_unban behave correctly
• Restarting the bot mid-chat preserves the pair
• The database contains metadata only — no message content

• Migrations are managed by Alembic. The container entrypoint runs alembic upgrade head before the bot starts, so deployments are always on the current schema. For manual (non-Docker) deployments, run alembic upgrade head yourself; alembic revision --autogenerate creates a new migration.
• Healthchecks are wired for Redis and PostgreSQL in docker-compose.yml; the bot waits for both to be healthy before starting.
• Scaling: the bot is stateless, so you can run several replicas against one Redis and one PostgreSQL. The matchmaking Lua script uses dynamic keys and therefore targets standalone Redis, not Redis Cluster.
• Backups: only the PostgreSQL volume holds anything worth backing up. Message content does not exist anywhere, by design.
• Logs contain startup information and unhandled errors only — never message content.

Contributions are welcome. Please read CONTRIBUTING.md for the development setup, the quality gates every pull request must pass, and the privacy expectations we hold to. Participation is governed by the Code of Conduct.

Please do not report vulnerabilities through public issues. See SECURITY.md for private disclosure instructions.

• Web admin dashboard for moderation and analytics
• Optional locale-based matchmaking preferences
• Prometheus metrics endpoint
• End-to-end test harness against the Telegram Bot API

Whisper is open source software licensed under the Apache License 2.0.

Copyright 2026 Amit Das
Licensed under the Apache License, Version 2.0.

The original concept and the legacy implementation of this bot are by mramitdas. Whisper is a ground-up rewrite of that project, released under the Apache 2.0 license.