Skip to content

README.md

Latest commit

 

History

History
391 lines (287 loc) · 15.1 KB

README.md

File metadata and controls

391 lines (287 loc) · 15.1 KB

Telegram-shop

Telegram shop bot is a template like this one, a Telegram store bot for managing a complete inventory store in Telegram. This Telegram Store Bot is for digital inventory.

Message me at @InDMDev for your advanced bot customizations. For more Bots like this, and to be the first to know when I publish free bots, join my channel: @InDMDevBots

Telegram bot for selling digital products: · sell software license keys on Telegram · Telegram shop/store bot · crypto payment bot · CryptoBot integration · Telegram Payments card checkout · automated digital delivery · Python e-commerce bot · python-telegram-bot store · SQLAlchemy SQLite Telegram bot · self-hosted digital goods storefront.

Digital Products Store — Telegram Bot

Python python-telegram-bot SQLAlchemy SQLite Platform License: MIT

A Telegram bot for selling digital products (software license keys and downloadable files). Customers browse a catalog, top up an internal wallet with crypto or card, and spend that balance on products. License keys are automatically delivered from inventory; file products are delivered via download links. A full in-Telegram admin panel handles products, categories, stock, orders, disputes, users, broadcasts, and store settings.

Built with Python, python-telegram-bot v20 (async), and SQLAlchemy (SQLite by default).

image

Table of Contents

  1. Features
  2. Tech Stack
  3. Project Structure
  4. Prerequisites
  5. Step 1 — Get your Telegram credentials
  6. Step 2 — Clone the repository
  7. Step 3 — Create a virtual environment
  8. Step 4 — Install dependencies
  9. Step 5 — Configure environment variables
  10. Step 6 — Run the bot
  11. Step 7 — Use the bot (/start and /admin)
  12. Optional — Real-time CryptoBot webhooks
  13. Optional — Keep the bot running 24/7
  14. Database notes
  15. Troubleshooting
  16. Security notes

Features

  • 🛒 Product catalog with categories and subcategories
  • 🔑 Two product types: license keys (auto-delivered from inventory) and downloadable files (delivered as links)
  • 💰 Internal wallet — users top up, then spend the balance on purchases
  • 💳 Two top-up methods, both optional and independently toggled by config:
    • CryptoBot — pay with any cryptocurrency via @CryptoBot
    • Card — native in-Telegram card payments via Telegram Payments
  • 🛠 Full in-Telegram admin panel: products, categories, stock/restock, orders, disputes, users (ban/unban), broadcasts, and store settings
  • ⏱ Background jobs for payment verification and periodic availability broadcasts

Tech Stack

Component Version
Python 3.10+ recommended (3.9+ supported)
python-telegram-bot 20.7
SQLAlchemy 2.0.23
Database SQLite (default) or PostgreSQL

How it fits together: bot.py is the single wiring point — it validates config (config/), initializes the database (database/), then registers all the handlers/. Handlers talk to Telegram and call into services/ (external APIs) and utils/ (keyboards + helpers); all data access goes through get_db_session() in database/db.py.

Prerequisites

Install these before you start:

Verify your tools are installed:

Windows (PowerShell):

git --version
python --version

Linux / macOS:

git --version
python3 --version

Step 1 — Get your Telegram credentials

You need a bot token and your admin Telegram ID. The two payment keys are optional.

1a. Bot token (required)

  1. Open @BotFather in Telegram.
  2. Send /newbot and follow the prompts (choose a name and a username ending in bot).
  3. Copy the API token it gives you (looks like 1234567890:ABCdef...).

1b. Your admin Telegram ID (required)

  1. Open @userinfobot in Telegram.
  2. Send any message; it replies with your numeric Id (e.g. 123456789).
  3. This ID is the only account that can access /admin.

1c. CryptoBot API key (optional — enables crypto top-ups)

  1. Open @CryptoBot → Crypto Pay → My Apps → create an app.
  2. Copy the API token. Leave blank to disable the CryptoBot option.

1d. Telegram Payments provider token (optional — enables card top-ups)

  1. Open @BotFather → select your bot → Payments.
  2. Connect a payment provider and copy the provider token. Leave blank to disable the Card option.

    Card-provider availability is region-dependent — pick a provider supported in your country. Use the provider’s TEST token while developing.

Step 2 — Clone the repository

Windows (PowerShell) and Linux / macOS (same commands):

git clone <YOUR_REPOSITORY_URL>
cd TelegramShop

Replace <YOUR_REPOSITORY_URL> with your repo’s clone URL, and TelegramShop with the folder name if it differs.

Step 3 — Create a virtual environment

A virtual environment keeps this project’s dependencies isolated.

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

If activation is blocked by execution policy, run once: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned (or use the CMD activator: venv\Scripts\activate.bat).

Linux / macOS:

python3 -m venv venv
source venv/bin/activate

When active, your shell prompt is prefixed with (venv). To leave it later, run deactivate.

Step 4 — Install dependencies

With the virtual environment active:

Windows (PowerShell):

python -m pip install --upgrade pip
pip install -r requirements.txt

Linux / macOS:

python3 -m pip install --upgrade pip
pip install -r requirements.txt

Step 5 — Configure environment variables

Copy the example file to a real .env and fill in your values.

Windows (PowerShell):

Copy-Item .env.example .env
notepad .env

Linux / macOS:

cp .env.example .env
nano .env

Fill in the variables:

Variable Required Description
BOT_TOKEN ✅ Bot token from @BotFather (Step 1a).
ADMIN_TELEGRAM_ID ✅ Your numeric Telegram ID (Step 1b). The only admin account.
ADMIN_TELEGRAM_USERNAME ➖ Your username without @ (used in some messages).
DATABASE_URL ➖ Defaults to sqlite:///bot_database.db. Set a PostgreSQL URL to use Postgres.
CRYPTO_BOT_API_KEY ➖ CryptoBot Crypto Pay token (Step 1c). Blank disables crypto top-up.
TELEGRAM_PROVIDER_TOKEN ➖ Telegram Payments provider token (Step 1d). Blank disables card top-up.
PAYMENT_CURRENCY ➖ Currency for card invoices (default USD). Must be USD-denominated to match wallet amounts.

The bot will not start until at least BOT_TOKEN and ADMIN_TELEGRAM_ID are set — it validates these on startup and exits with a clear message if either is missing.

Step 6 — Run the bot

The database is created and seeded automatically on first run — there is no separate setup command.

Windows (PowerShell):

python bot.py

Linux / macOS:

python3 bot.py

You should see log lines ending with:

Bot started successfully!

Leave this terminal open — the bot runs as long as the process is running. Press Ctrl+C to stop it.

Step 7 — Use the bot (/start and /admin)

With the bot running:

  1. Open Telegram and search for your bot by the username you chose in Step 1a.
  2. Send /start — you’ll get the welcome message and the main menu (Products, Top Up, Order History, Availability, Support).
  3. Send /admin — if your Telegram ID matches ADMIN_TELEGRAM_ID, the admin panel opens (Product Management, User Management, Order Management, Store Settings, Broadcast).

If /admin says access is denied or does nothing, your ADMIN_TELEGRAM_ID doesn’t match your account — recheck Step 1b, fix .env, and restart the bot.

🎉 That’s it — your bot is live. A typical first run as admin: open /admin → Product Management → create a category, then a product, then Restock Keys to add inventory. As a user, /start → Top Up to fund the wallet, then buy a product.

Optional — Real-time CryptoBot webhooks

By default, CryptoBot payments are confirmed by polling every ~30 seconds (no extra setup). For instant confirmation, run the included webhook server alongside the bot.

  1. Start the webhook server (separate terminal, same virtual environment):

    Windows (PowerShell):

    python webhook_server.py

    Linux / macOS:

    python3 webhook_server.py

    It listens on port 5000.

  2. Expose it over HTTPS (e.g. with ngrok):

    ngrok http 5000

  3. In @CryptoBot → Crypto Pay → My Apps → Webhooks, set the URL to:

    https://<your-ngrok-or-domain>/webhook/cryptobot

On Windows, you can launch the bot and the webhook server together with start_with_webhooks.bat (you still run ngrok yourself). Card payments need no webhook — Telegram delivers their confirmation through the bot’s normal update polling.

Optional — Keep the bot running 24/7

Linux (systemd)

Create /etc/systemd/system/digitalstore-bot.service (adjust paths and User):

[Unit]
Description: Digital Products Store Telegram Bot
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/TelegramShop
ExecStart=/home/youruser/TelegramShop/venv/bin/python bot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now digitalstore-bot
sudo systemctl status digitalstore-bot      # check it's running
journalctl -u digitalstore-bot -f            # follow logs

Windows

Keep the python bot.py window open, or run it as a background/scheduled task (e.g. Task Scheduler), or host it on a Linux server using the steps above.

Database notes

  • Default: SQLite, stored in bot_database.db in the project folder. Created automatically on first run.

  • Backup: simply copy the bot_database.db file.

  • Reset (deletes all data): stop the bot, delete bot_database.db, and start the bot again to recreate an empty database.

    Windows (PowerShell):

    Remove-Item bot_database.db

    Linux / macOS:

    rm bot_database.db

  • PostgreSQL (optional): set DATABASE_URL to a Postgres URL, e.g. postgresql+psycopg2://user:password@localhost:5432/digitalstore (The psycopg2-binary driver is already in requirements.txt).

  • Upgrading an older database: if you’re migrating an existing SQLite DB created before category fields were made optional, run once: python migrations/001_make_category_id_nullable.py (not needed for fresh installs).

Troubleshooting

Symptom Fix
Configuration error: BOT_TOKEN is required .env is missing or BOT_TOKEN/ADMIN_TELEGRAM_ID is empty. Recheck Step 5 and that .env is in the project root.
/admin denied or no response ADMIN_TELEGRAM_ID doesn’t match your account. Re-get your ID (Step 1b), update .env, restart.
ModuleNotFoundError / import errors The virtual environment isn’t active or deps aren’t installed. Re-do Step 3 and Step 4.
python not found (Windows) Reinstall Python with “Add Python to PATH” ticked, or use the py launcher (py bot.py).
Activation blocked (Windows) Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned, then re-activate.
Card button shows “not configured” TELEGRAM_PROVIDER_TOKEN is blank or invalid — see Step 1d.
Crypto top-up not auto-confirming Verify CRYPTO_BOT_API_KEY, check the console for API errors, or set up webhooks for instant confirmation.
Bot stops when you close the terminal That’s expected — use the 24/7 section.

FAQ

What is this project? An open-source, self-hosted Telegram bot for selling digital products — software license/activation keys and downloadable files — with a customer-facing storefront and a full admin panel, all inside Telegram.

What can I sell with it? Anything digital: software license keys, game keys, gift-card codes, e-books, PDFs, courses, templates, or any downloadable file delivered via a link.

How do customers pay? Customers fund an in-bot wallet, then spend the balance on purchases. Top-ups are supported via CryptoBot (any cryptocurrency) and card payments (Telegram Payments). Both methods are optional and toggled by config.

Is delivery automatic? Yes. License keys are assigned automatically from your inventory the moment a purchase is confirmed; file products are delivered as a download link — no manual fulfillment.

Do I need to know how to code to run it? No. Clone the repo, fill in a .env file, and run one command. The database is created automatically on first launch.

Which database does it use? SQLite by default (zero setup). You can switch to PostgreSQL by changing a single environment variable.

Does it work on Windows and Linux? Yes — the setup guide has step-by-step commands for Windows, Linux, and macOS, plus a systemd service for 24/7 hosting.

Is it free and open source? Yes — released under the MIT License.

License

Released under the MIT License.

⚠️ Note: Use this program only for legal purposes. InDMDev is not and will not be responsible for any illegal activity/activities you indulge in using any of our programs.