AiogramShopBot

AiogramShopBot is a software product based on Aiogram3 and SQLAlchemy that allows you to automate sales of digital goods in Telegram. goods in Telegram. One of the bot's advantages is that AiogramShopBot implements the ability to top up with Bitcoin, Litecoin, Solana and stablecoins in the TRC20 and ERC20 networks, which allows you to sell digital goods worldwide.

• 🤝 Commercial offers
  • ➤ Telegram.
  • 🤖 AiogramShopBotDemo.
• ✨ Donate
• 1.Launch the bot
  • 1.0 Description of required environment variables.
  • 1.1 Launch AiogramShopBot with Docker-compose.
  • 1.2 Launch AiogramShopBot without SQLCipher database encryption.
  • 1.3 Launch AiogramShopBot with SQLCipher database encryption.
• 2. 👥 AiogramShopBot User's Manual
  • 2.1 🖥️ Registration
  • 2.2 ➕ Top Up Balance
  • 2.3 👜 Purchase of goods
  • 2.4 🧾 Purchase History
• 3. 🔑 AiogramShopBot Admin Manual
  • 3.1 🔑 Adding a new admin
  • 3.2 📢 Announcements
    • 3.2.1 📢 Send to Everyone
    • 3.2.2 🔄 Restocking Message
    • 3.2.3 🗂️ Current Stock
  • 3.3 📦 Inventory Management
    • 3.3.1 ➕ Add Items
      • 3.3.1.1 JSON
      • 3.3.1.2 TXT
  • 3.4 👥 User Management
    • 3.4.1 💳 Credit Management
      • 3.4.1.1 ➕ Add balance
      • 3.4.1.2 ➖ Reduce balance
    • 3.4.2 ↩️ Make Refund
  • 3.5 📊 Analytics & Reports
  • 3.6 🔔 Admin notifications
• 4.0 Multibot (Experimental functionality)
  • 4.1 Starting the multibot
• 📋 Todo List
• MIT License

📌Commercial offers

➤ For commercial offers contact me on Telegram.

🤖 You can test the functionality in AiogramShopBotDemo.

Donate ✨

• BTC - bc1q2kv89q8yvf068xxw3x65gzfag98l9wnrda3x56
• LTC - ltc1q0tuvm5vqn9le5zmhvhtp7z9p2eu6yvv24ey686
• TRX - THzRw8UpTsEYBEG5CCbsCVnJzopSHFHJm6
• SOL - Avm7VAqPrwpHteXKfDTRFjpj6swEzjmj3a2KQvVDvugK
• ETH - 0xB49D720DE2630fA4C813d5B4c025706E25cF74fe
• TON - UQD0QetwXoYTsmbZWVbE_z_JUFh54RVVRUxCbCHQkLsl3Hfn
• USDT ERC20 - 0xB49D720DE2630fA4C813d5B4c025706E25cF74fe
• USDT BEP20 - 0xB49D720DE2630fA4C813d5B4c025706E25cF74fe
• USDT TRC20 - THzRw8UpTsEYBEG5CCbsCVnJzopSHFHJm6

1.Starting the bot

1.0 Description of required environment variables

Environment Variable Name	Description	Recommend Value
WEBHOOK_PATH	The path to the webhook where Telegram servers send requests for bot updates. It is not recommended to change it if only one bot will be deployed. In case several bots will be deployed on the same server, it will be necessary to change it, because there will be path collision (Does not apply to the multibot case).	"" (empty string)
WEBAPP_HOST	Hostname for Telegram bot, it is not recommended to change in case you use docker-compose.	For docker-compose="0.0.0.0". For local deployment="localhost".
WEBAPP_PORT	Port for Telegram bot, if you plan to deploy several bots on the same server, you will need to assign a different port to each one (Not relevant to the multibot case).	No recommended value
TOKEN	Token from your Telegram bot, you can get it for free in Telegram from the bot of all bots with the username @botfather.	No recommended value
ADMIN_ID_LIST	List of Telegram id of all admins of your bot. This list is used to check for access to the admin menu.	No recommended value
SUPPORT_LINK	A link to the Telegram profile that will be sent by the bot to the user when the “Help” button is pressed.	https://t.me/${YOUR_USERNAME_TG}
DB_NAME	The name of the SQLite database file.	database.db
DB_ENCRYPTION	Boolean variable that enables database encryption.	"true" of "false"
DB_PASS	Needs only if DB_ENCRYPTION=='true'. The password that will be used to encrypt your SQLite database with SQLCipher.	Any string less than 31 characters
NGROK_TOKEN	Token from your NGROK profile, it is needed for port forwarding to the Internet. The main advantage of using NGROK is that NGROK assigns the HTTPS certificate for free.	No recommended value
PAGE_ENTRIES	The number of entries per page. Serves as a variable for pagination.	8
BOT_LANGUAGE	The name of the .json file with the l10n localization. At the moment only English localization is supplied out of the box, but you can make your own if you create a file in the l10n folder with the same keys as in l10n/en.json.	"en" or "de"
MULTIBOT	Experimental functionality, allows you to raise several bots in one process. And there will be one main bot, where you can create other bots with the command “/add $BOT_TOKEN”. Accepts string parameters “true” or “false”.	"false"
ETHPLORER_API_KEY	API Key from ethplorer.io, used to get ERC20 balances.	No recommended value
CURRENCY	Currency to be used in the bot.	"USD" or "EUR" or "JPY" or "CAD" or "GBP"

1.1 Starting AiogramShopBot with Docker-compose.

• Clone the project.
  git clone git@github.com:ilyarolf/AiogramShopBot.git
• Set environment variables in docker-compose.yml file.
• Run the docker-compose up command.

Note
To get the ngrok token, you need to register on the ngrok website and confirm your email. Then you will have the ngrok token in your personal account.

1.2 Starting AiogramShopBot without database encryption.

• Clone the project from the master branch.
  git clone git@github.com:ilyarolf/AiogramShopBot.git
• Install all necessary packages
  pip install -r requirements.txt
• Set the environment variables to run in the .env file.
  Example:

WEBHOOK_PATH = ""
WEBAPP_HOST = "localhost"
WEBAPP_PORT = 5000
TOKEN = "1234567890:QWER.....TYI"
ADMIN_ID_LIST = 123456,654321
SUPPORT_LINK = "https://t.me/your_username_123"
DB_NAME = "database.db"
DB_ENCRYPTION = "false"
DB_PASS = ""
NGROK_TOKEN = "NGROK_TOKEN_HERE"
PAGE_ENTRIES = 8
BOT_LANGUAGE = "en"
MULTIBOT = "false"
ETHPLORER_API_KEY = "API_KEY_HERE"
CURRENCY = "USD"

• After these steps the bot is ready to run, launch the bot with command python run.py

1.3 Starting AiogramShopBot with SQLCipher database encryption.

Note
To run AiogramShopBot with database encryption via SQLCipher, you need to use Linux kernel operating systems.

• Clone the project. branch.
  git clone git@github.com:ilyarolf/AiogramShopBot.git
• Install the SQLCipher package, for example in Ubuntu this can be done with the command
  sudo apt install sqlcipher.
• Install all necessary packages
  pip install -r requirements.txt
• Install SQLCipher python package
  pip install sqlcipher3
• Set the environment variables to run in the .env file.
  Example:

WEBHOOK_PATH = ""
WEBAPP_HOST = "localhost"
WEBAPP_PORT = 5000
TOKEN = "1234567890:QWER.....TYI"
ADMIN_ID_LIST = 123456,654321
SUPPORT_LINK = "https://t.me/your_username_123"
DB_NAME = "database.db"
DB_ENCRYPTION = "true"
DB_PASS = "1234567890qwertyui"
NGROK_TOKEN = "NGROK_TOKEN_HERE"
PAGE_ENTRIES = 8
BOT_LANGUAGE = "en"
MULTIBOT = "false"
ETHPLORER_API_KEY = "API_KEY_HERE"
CURRENCY = "USD"

• After these steps the bot is ready to run, the entry point to run the bot is run.py
  python run.py

2.AiogramShopBot User's Manual

2.1 Registration

User registration occurs when the bot is first accessed with the /start command. Each user is assigned a different mnemonic phrase to generate BTC, LTC, USDT TRC20 crypto addresses. BTC and LTC addresses are generated according to BIP-84 standard, for USDT TRC20 the BIP-44 standard is used, this is done so that wallets can be easily imported into Trust Wallet.

2.2 ➕ Top Up Balance

• Open my profile menu using the “👤 My profile” button.
• Open top-up menu using the “➕ Top Up Balance” button.
• In the resulting menu, click on cryptocurrency name button.
• Copy cryptocurrency address, and send cryptocurrency on this address.
• Once your transaction has at least one confirmation, click on the “🔄 Refresh balance” button.

Note "Refresh balance" button has a 30 seconds cooldown.

2.3 Purchase of goods

To buy any item, go to "All categories" -> Select any category -> Select any subcategory -> Select quantity -> Confirm purchase. If the purchase is successful, you will immediately receive a message in the format:

2.4 🧾 Purchase History

• To access your purchase history go to "My Profile" -> "Purchase History".
• You will be presented with an inline keyboard with all your purchases, by clicking on any of the purchases you will be sent a message in the format from paragraph 2.3.

3.AiogramShopBot Admin Manual

3.1 Adding a new admin

To add a new admin you need to add his telegram id to the ADMIN_ID_LIST environment variable, separated by commas, and reload the bot.
For example: ADMIN_ID_LIST=123456,654321

3.2 📢 Announcements

3.2.1 📢 Send to Everyone

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the announcements menu using the “📢 Announcements” button.
• In the resulting menu, click on “📢 Send to Everyone” button.
• Type a message or forward to the bot, the bot supports sending a message with pictures and Telegram markup (bold, italics, spoilers, etc.).
• Confirm or decline the sending of messages.
• After successful message sending, the original message with inline buttons "Confirm", "Decline" will change like on gif.
  

3.2.2 🔄 Restocking Message

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the announcements menu using the “📢 Announcements” button.
• In the resulting menu, click on “🔄 Restocking Message” button.
• This message is generated based on items in the database that have "is_new" is true.

3.2.3 🗂️ Current Stock

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the announcements menu using the “📢 Announcements” button.
• In the resulting menu, click on “🗂️ Current Stock” button.
• This message is generated based on items in the database that have "is_sold" is false.

3.3 📦 Inventory Management

3.3.1 ➕ Add Items

3.3.1.1 JSON

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the announcements menu using the “📦 Inventory Management” button.
• Open the add items menu using the “➕ Add Items” button.
• In the resulting menu, click on “JSON” button.
• Send .json file with new items.
  Example of .json file:

Note The "private_data" property is what the user gets when they make a purchase.

[
  {
    "category": "Category#1",
    "subcategory": "Subcategory#1",
    "price": 50,
    "description": "Mocked description",
    "private_data": "Mocked private data"
  },
  {
    "category": "Category#2",
    "subcategory": "Subcategory#2",
    "price": 100,
    "description": "Mocked description",
    "private_data": "Mocked private data"
  }
]

3.3.1.2 TXT

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the inventory management menu using the “📦 Inventory Management” button.
• Open the add items menu using the “➕ Add Items” button.
• In the resulting menu, click on “TXT” button.
• Send .txt file with new items.
  Example of .txt file:

CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#1
CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#2
CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#3
CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#4
CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#5
CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#6
CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#7
CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#8

3.3.2 🗑️ Delete Category/Subcategory

Note: This way, you will delete all products from “All categories” with the category or subcategory you picked and deleted.

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the inventory management menu using the “📦 Inventory Management” button.
• Open the add items menu using the “🗑️ Delete Category” or “🗑️ Delete Subcategory” button.
• In the resulting menu, select the category or subcategory you want to delete.
• Confirm or cancel the deletion of the category or subcategory.

3.4 👥 User Management

3.4.1 💳 Credit Management

3.4.1.1 ➕ Add balance

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the user management menu using the “👥 User Management” button.
• Open the credit management menu using the “💳 Credit Management” button.
• In the resulting menu, click on “➕ Add balance” button.
• Send the user entity object that belongs to the user you want to add the balance to. This can be telegram id or telegram username.
• Send the value by which you want to add the balance to the user.

3.4.1.2 ➖ Reduce balance

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the user management menu using the “👥 User Management” button.
• Open the credit management menu using the “💳 Credit Management” button.
• In the resulting menu, click on “➖ Reduce balance” button.
• Send the user entity object that belongs to the user you want to add the balance to. This can be telegram id or telegram username.
• Send the value by which you want to reduce the balance to the user.

3.4.2 ↩️ Make Refund

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the user management menu using the “👥 User Management” button.
• Open the refund menu using the “↩️ Make Refund” button.
• In the resulting menu, click on the buy button you want to refund.
• Confirm or cancel refund.

3.5 📊 Analytics & Reports

3.5.1 📊 Statistics

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the statistics menu using the “📊 Analytics & Reports” button.
• In the resulting menu, click on the entity for which you want to get statistics.
• In the resulting menu, click on the time period for which you want statistics.

3.5.2 💾 Get database file

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the statistics menu using the “📊 Analytics & Reports” button.
• Click "💾 Get database file" button.

3.6 🔔 Admin notifications

Note All users with telegram id in the .env ADMIN_ID_LIST environment variable will receive these notifications

3.8.1 Notification to admin about new deposit

• If any user topped up the balance and clicked on the "Refresh balance" button, you will receive the following message from the bot:

3.8.2 Notification to admin about new buy

After each purchase, you will receive a message in the format:

4.0 Multibot (Experimental functionality)

4.1 Starting the multibot

• Set all environment variables in docker-compose.yml and set the variable “true” for MULTIBOT. MULTIBOT="true"
• Run the docker-compose up command.
• After successful execution of the command, you will only deploy a manager bot for other bots, it will not have functionality for buying items etc. To deploy a bot with functionality to sell goods etc..., you need to send the command /add $TOKEN to the bot manager. If everything is successful, you will receive this notification.

📋 Todo List

• Make migration from direct raw database queries to SQLAlchemy ORM.
• Add option to encrypt database via SQLCipher (when using SQLAlchemy).
• Add an option to generate new crypto addresses using new mnemonic phrases so that 1 user=1 mnemonic phrase.
• Items pagination.
• Make the functionality of database backup by action in the admin in the Telegram bot.
• Make the functionality of generating statistics of sales and users in the bot for a month/week/day in the admin panel.
• Make the functionality of generating statistics of deposits in the bot for a month/week in the admin panel.