+[everyone-mention-telegram-bot](http://t.me/everyone_mention_bot) +
+
simple, but useful telegram bot to gather all of group members attention! + + +## Contents + +* [Getting started.](#getting-started) + * [Installation](#installation) + * [Requirements](#requirements) + * [Env file](#env-file) +* [Commands](#commands) + * [`/in`](#in) + * [`/out`](#out) + * [`/everyone`](#everyone) + +### Getting started +#### Installation +```bash +git clone https://github.com/miloszowi/everyone-mention-telegram-bot.git +pip install -r requirements.txt +python entrypoint.py +``` + +#### Requirements +- `python` with version specified in `runtime.txt` +- `pip` with version `20.0.2` + +#### Env file +```bash +cp .env.local .env +``` +and then fulfill copied `.env` file with required values +- `bot_token` - your telegram bot token from [BotFather](https://telegram.me/BotFather) +- `firebase_*` - all of those values you can find in firebase console +- `app_url` - your app url for retrieving webhooks +- `PORT` - port for your app + +### Commands +#### `/in` +Will sign you in for everyone-mentions. + + + +If you have already opted-in before, alternative reply will be displayed. + + + +#### `/out` +Will sign you off for everyone-mentions. + + + +If you haven't opted-in before, alternative reply will be displayed. + + + +#### `/everone` +Will mention everyone that opted-in for everyone-mentions separated by spaces. + +If user does not contain nickname, his ID will be present instead of nickname. + + + +If there are no users that opted-in for mentioning, alternative reply will be displayed. + + diff --git a/docs/commands.png b/docs/commands.png new file mode 100644 index 0000000..24caf9d Binary files /dev/null and b/docs/commands.png differ diff --git a/docs/everyone_command.png b/docs/everyone_command.png new file mode 100644 index 0000000..37c75c9 Binary files /dev/null and b/docs/everyone_command.png differ diff --git a/docs/everyone_noone_to_mention.png b/docs/everyone_noone_to_mention.png new file mode 100644 index 0000000..88200a1 Binary files /dev/null and b/docs/everyone_noone_to_mention.png differ diff --git a/docs/in_command.png b/docs/in_command.png new file mode 100644 index 0000000..fc08bcf Binary files /dev/null and b/docs/in_command.png differ diff --git a/docs/in_command_already_opted_in.png b/docs/in_command_already_opted_in.png new file mode 100644 index 0000000..4370a08 Binary files /dev/null and b/docs/in_command_already_opted_in.png differ diff --git a/docs/logo.png b/docs/logo.png new file mode 100644 index 0000000..5e76b51 Binary files /dev/null and b/docs/logo.png differ diff --git a/docs/out_command.png b/docs/out_command.png new file mode 100644 index 0000000..062b913 Binary files /dev/null and b/docs/out_command.png differ diff --git a/docs/out_command_did_not_opt_in_before.png b/docs/out_command_did_not_opt_in_before.png new file mode 100644 index 0000000..f7a7732 Binary files /dev/null and b/docs/out_command_did_not_opt_in_before.png differ diff --git a/entrypoint.py b/entrypoint.py new file mode 100644 index 0000000..2e270f8 --- /dev/null +++ b/entrypoint.py @@ -0,0 +1,6 @@ +from src.app import App + +if __name__ == "__main__": + app = App() + + app.run() diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..af1197a --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +python-dotenv==0.19.0 +python-telegram-bot==13.7 +Pyrebase==3.0.27 diff --git a/runtime.txt b/runtime.txt new file mode 100644 index 0000000..a48890e --- /dev/null +++ b/runtime.txt @@ -0,0 +1 @@ +python-3.8.10 diff --git a/src/app.py b/src/app.py new file mode 100644 index 0000000..42eb3d2 --- /dev/null +++ b/src/app.py @@ -0,0 +1,34 @@ +from .config.credentials import bot_token, app_url, port +from .config.handlers import handlers +from .handlers.handlerInterface import HandlerInterface +from telegram.ext.dispatcher import Dispatcher +from telegram.ext import Updater + + +class App: + updater: Updater + dispatcher: Dispatcher + + def __init__(self): + self.updater = Updater(bot_token) + + def run(self) -> None: + self.registerHandlers() + self.registerWebhook() + + self.updater.idle() + + def registerHandlers(self) -> None: + for handler in handlers: + if not isinstance(handler, HandlerInterface): + raise Exception('Invalid list of handlers provided. Handler must implement HandlerInterface') + + self.updater.dispatcher.add_handler(handler.getBotHandler()) + + def registerWebhook(self) -> None: + self.updater.start_webhook( + listen="0.0.0.0", + port=int(port), + url_path=bot_token, + webhook_url=f'{app_url}/{bot_token}' + ) diff --git a/src/config/contents.py b/src/config/contents.py new file mode 100644 index 0000000..d36c2fc --- /dev/null +++ b/src/config/contents.py @@ -0,0 +1,8 @@ +import re + +# These are MarkdownV2 python-telegram-bot specific +opted_in_successfully = re.escape('You have opted-in for everyone-mentions.') +opted_in_failed = re.escape('You already opted-in for everyone-mentions.') +opted_off_successfully = re.escape('You have opted-off for everyone-mentions.') +opted_off_failed = re.escape('You need to opt-in first before processing this command.') +mention_failed = re.escape('There are no users to mention.') diff --git a/src/config/credentials.py b/src/config/credentials.py new file mode 100644 index 0000000..8cb7c00 --- /dev/null +++ b/src/config/credentials.py @@ -0,0 +1,16 @@ +import os +from dotenv import load_dotenv + +load_dotenv() + +bot_token = os.environ['bot_token'] +app_url = os.environ['app_url'] +port = os.environ['PORT'] + +firebaseConfig = { + "apiKey": os.environ['firebase_apiKey'], + "authDomain": os.environ['firebase_authDomain'], + "databaseURL": os.environ['firebase_databaseURL'], + "projectId": os.environ['firebase_projectId'], + "storageBucket": os.environ['firebase_storageBucket'], +} diff --git a/src/config/handlers.py b/src/config/handlers.py new file mode 100644 index 0000000..a7d81d6 --- /dev/null +++ b/src/config/handlers.py @@ -0,0 +1,9 @@ +from ..handlers.inHandler import InHandler +from ..handlers.outHandler import OutHandler +from ..handlers.mentionHandler import MentionHandler + +handlers = [ + InHandler(), + OutHandler(), + MentionHandler() +] diff --git a/src/firebaseProxy.py b/src/firebaseProxy.py new file mode 100644 index 0000000..aa8db8c --- /dev/null +++ b/src/firebaseProxy.py @@ -0,0 +1,34 @@ +import pyrebase +from pyrebase.pyrebase import Database as FirebaseDB +from .config.credentials import firebaseConfig + + +class FirebaseProxy(): + db: FirebaseDB + + # Group specific values + group_index: str = 'groups' + + # User specific values + id_index: str = 'id' + name_index: str = 'name' + + def __init__(self) -> None: + firebase = pyrebase.pyrebase.initialize_app(firebaseConfig) + self.db = firebase.database() + + def getChilds(self, *childs: str) -> FirebaseDB: + current = self.db + + for child_index in childs: + current = current.child(child_index) + + return current + + @staticmethod + def getGroupPath(groupId: int) -> str: + return f'{FirebaseProxy.group_index}/{groupId}' + + @staticmethod + def getUserPath(userId: int, groupId: int) -> str: + return f'{groupId}_{userId}' diff --git a/src/handlers/handlerInterface.py b/src/handlers/handlerInterface.py new file mode 100644 index 0000000..3cad7ce --- /dev/null +++ b/src/handlers/handlerInterface.py @@ -0,0 +1,18 @@ +from abc import abstractmethod +from telegram.ext.callbackcontext import CallbackContext +from telegram.ext.handler import Handler +from telegram.update import Update + + +class HandlerInterface: + def __init__(self) -> None: + pass + + @abstractmethod + def getBotHandler(self) -> Handler: raise Exception('getBotHandler method is not implemented') + + @abstractmethod + def handle(self, update: Update, context: CallbackContext) -> None: raise Exception('handle method is not implemented') + + @abstractmethod + def getCommandName(self) -> str: raise Exception('getCommandName method is not implemented') diff --git a/src/handlers/inHandler.py b/src/handlers/inHandler.py new file mode 100644 index 0000000..5f55e1c --- /dev/null +++ b/src/handlers/inHandler.py @@ -0,0 +1,39 @@ +from ..config.contents import opted_in_successfully, opted_in_failed +from ..repositories.userRepository import UserRepository +from ..firebaseProxy import FirebaseProxy +from .handlerInterface import HandlerInterface +from telegram.ext.callbackcontext import CallbackContext +from telegram.ext.commandhandler import CommandHandler +from telegram.update import Update + + +class InHandler(HandlerInterface): + botHandler: CommandHandler + commandName: str = 'in' + + def __init__(self) -> None: + self.botHandler = CommandHandler( + self.getCommandName(), + self.handle + ) + + def handle(self, update: Update, context: CallbackContext) -> None: + groupId = update.effective_chat.id + userData = { + FirebaseProxy.id_index: update.effective_user.id, + FirebaseProxy.name_index: update.effective_user.username + } + userRepository = UserRepository() + + if userRepository.isPresentInGroup(userData.get(FirebaseProxy.id_index), groupId): + update.message.reply_markdown_v2(text=opted_in_failed) + return + + userRepository.addForGroup(userData, groupId) + update.message.reply_markdown_v2(text=opted_in_successfully) + + def getBotHandler(self) -> CommandHandler: + return self.botHandler + + def getCommandName(self) -> str: + return self.commandName diff --git a/src/handlers/mentionHandler.py b/src/handlers/mentionHandler.py new file mode 100644 index 0000000..cef012c --- /dev/null +++ b/src/handlers/mentionHandler.py @@ -0,0 +1,42 @@ +from ..config.contents import mention_failed +from ..firebaseProxy import FirebaseProxy +from ..repositories.groupRepository import GroupRepository +from .handlerInterface import HandlerInterface +from telegram.ext.callbackcontext import CallbackContext +from telegram.ext.commandhandler import CommandHandler +from telegram.update import Update + + +class MentionHandler(HandlerInterface): + botHandler: CommandHandler + commandName: str = 'everyone' + + def __init__(self) -> None: + self.botHandler = CommandHandler( + self.getCommandName(), + self.handle + ) + + def handle(self, update: Update, context: CallbackContext) -> None: + groupId = update.effective_chat.id + groupRepository = GroupRepository() + mentionMessage = self.buildMentionMessage(groupRepository.get(id=groupId)) + + update.message.reply_markdown_v2(text=mentionMessage) + + def getBotHandler(self) -> CommandHandler: + return self.botHandler + + def getCommandName(self) -> str: + return self.commandName + + def buildMentionMessage(self, usersData: dict) -> str: + result = '' + + for userData in usersData: + userId = str(userData.get(FirebaseProxy.id_index)) + username = userData.get(FirebaseProxy.name_index) or userId + + result += "*[%s](tg://user?id=%s)* " % (username, userId) + + return result or mention_failed diff --git a/src/handlers/outHandler.py b/src/handlers/outHandler.py new file mode 100644 index 0000000..e102829 --- /dev/null +++ b/src/handlers/outHandler.py @@ -0,0 +1,39 @@ +from ..config.contents import opted_off_successfully, opted_off_failed +from ..repositories.userRepository import UserRepository +from .handlerInterface import HandlerInterface +from telegram.ext.callbackcontext import CallbackContext +from telegram.ext.commandhandler import CommandHandler +from telegram.update import Update + + +class OutHandler(HandlerInterface): + botHandler: CommandHandler + commandName: str = 'out' + + def __init__(self) -> None: + self.botHandler = CommandHandler( + self.getCommandName(), + self.handle + ) + + def handle(self, update: Update, context: CallbackContext) -> None: + groupId = update.effective_chat.id + userData = { + 'id': update.effective_user.id, + 'name': update.effective_user.username + } + + userRepository = UserRepository() + if not userRepository.isPresentInGroup(userData.get('id'), groupId): + update.message.reply_markdown_v2(text=opted_off_failed) + return + + userRepository.removeForGroup(userId=userData.get('id'), groupId=groupId) + + update.message.reply_markdown_v2(text=opted_off_successfully) + + def getBotHandler(self) -> CommandHandler: + return self.botHandler + + def getCommandName(self) -> str: + return self.commandName diff --git a/src/repositories/groupRepository.py b/src/repositories/groupRepository.py new file mode 100644 index 0000000..9747ab4 --- /dev/null +++ b/src/repositories/groupRepository.py @@ -0,0 +1,18 @@ +from ..firebaseProxy import FirebaseProxy + + +class GroupRepository(): + firebase: FirebaseProxy + + def __init__(self) -> None: + self.firebase = FirebaseProxy() + + def get(self, id: int) -> dict: + result = [] + groupData = self.firebase.getChilds(FirebaseProxy.group_index, id).get() + + if groupData.each(): + for user_root in groupData.each(): + result.append(user_root.val()) + + return result diff --git a/src/repositories/userRepository.py b/src/repositories/userRepository.py new file mode 100644 index 0000000..d1d472b --- /dev/null +++ b/src/repositories/userRepository.py @@ -0,0 +1,30 @@ +from ..firebaseProxy import FirebaseProxy + + +class UserRepository(): + firebaseProxy: FirebaseProxy + + def __init__(self) -> None: + self.firebaseProxy = FirebaseProxy() + + def addForGroup(self, userData: dict, groupId: int) -> None: + self.firebaseProxy.getChilds(FirebaseProxy.getGroupPath(groupId)).update({ + f'{groupId}_{userData.get("id")}': { + FirebaseProxy.id_index: userData.get("id"), + FirebaseProxy.name_index: userData.get("name") + } + }) + + def removeForGroup(self, userId: int, groupId: int) -> None: + self.firebaseProxy.getChilds(FirebaseProxy.getGroupPath(groupId)).update({ + FirebaseProxy.getUserPath(userId, groupId): {} + }) + + def isPresentInGroup(self, userId: int, groupId: int) -> bool: + user = self.firebaseProxy.getChilds( + FirebaseProxy.getGroupPath(groupId), + FirebaseProxy.getUserPath(userId, groupId) + ).get().val() + + return bool(user) + \ No newline at end of file