(20241206) Telegram Client half complete.

utils_v2/telegram/models/behaviour/telegram_bot.py

@@ -44,6 +44,7 @@ from utils_v2.date_time import date_time
 
 # Data models:
 from utils_v2.telegram.models.data.api_call import TelegramApiResponse
+from utils_v2.telegram.models.data.update import TelegramUpdate
 
 # To make API calls:
 import httpx
@@ -294,6 +295,14 @@ class AsyncTelegramBot:
             webhook_url: str
     ) -> TelegramApiResponse:
 
+        """
+        To set up a webhook to start receiving updates from Telegram. Use this same method to update an existing webhook
+        without having to call the 'delete_webhook' method first.
+        NOTE: WHEN A WEBHOOK IS SET, YOU CANNOT MANUALLY PULL UPDATES USING THE 'get_updates' METHOD.
+        :param webhook_url: The URL on which Telegram must send you updates for this bot.
+        :return: A standard response structure.
+        """
+
         # Make the API call:
         api_response = await self.__post(
             url = f"https://api.telegram.org/bot{self.__bot_token}/setWebhook",
@@ -315,6 +324,13 @@ class AsyncTelegramBot:
             self,
     ) -> TelegramApiResponse:
 
+        """
+        To stop receiving updates for this bot via the webhook. You can call this at any time even if no webhook is
+        active, and you just want to be sure.
+        NOTE: WHEN A WEBHOOK IS SET, YOU CANNOT MANUALLY PULL UPDATES USING THE 'get_updates' METHOD.
+        :return: A standard response structure.
+        """
+
         # Make the API call:
         api_response = await self.__get(
             url = f"https://api.telegram.org/bot{self.__bot_token}/deleteWebhook",
@@ -331,6 +347,11 @@ class AsyncTelegramBot:
         # Done here:
         return api_response
 
+    # ┳┳┓        ┓┓    ┏┓  ┓┓  ┳┓
+    # ┃┃┃┏┓┏┓┓┏┏┓┃┃┓┏  ┃┃┓┏┃┃  ┃┃┏┓╋┏┓
+    # ┛ ┗┗┻┛┗┗┻┗┻┗┗┗┫  ┣┛┗┻┗┗  ┻┛┗┻┗┗┻
+    #               ┛
+
     async def get_updates(
             self,
             update_id: int = None,
@@ -338,6 +359,17 @@ class AsyncTelegramBot:
             timeout: int | float = 30.0
     ) -> TelegramApiResponse:
 
+        """
+        To manually pull updates from Telegram.
+        NOTE: THIS DOES NOT WORK WHILE A WEBHOOK IS SET UP. YOU CAN EITHER USE THIS OR A WEBHOOK, NOT BOTH
+        SIMULTANEOUSLY.
+        :param update_id: The starting update id from where you want to start fetching updates. Leave this as None to
+            fetch all available updates. Useful for when the webhook goes down and updates get missed.
+        :param limit: The no. of updates to fetch.
+        :param timeout: The max. timeout in seconds for long-polling.
+        :return: A standard response structure with a list of 'TelegramUpdate's in the 'data' field.
+        """
+
         # Make the API call:
         api_response = await self.__get(
             url = f"https://api.telegram.org/bot{self.__bot_token}/getUpdates",
@@ -353,8 +385,9 @@ class AsyncTelegramBot:
             api_json = await api_response.get_json()
             # api_response.message = api_json["description"]
             api_response.data = api_json
-            # if api_json["ok"]:
-            #     api_response.success = True
+            if api_json["ok"]:
+                api_response.success = True
+                api_response.data = [TelegramUpdate(**r) for r in api_json["result"]]
 
         # Done here:
         return api_response
@@ -381,7 +414,7 @@ if __name__ == "__main__":
         # tg_response = await my_tg.bot_info()
         # tg_response = await my_tg.set_webhook(webhook_url = r"https://api.thecaoffice.com/converse/chat/webhook/123")
         # tg_response = await my_tg.delete_webhook()
-        tg_response = await my_tg.get_updates(update_id = 946018731, limit = 5)
+        tg_response = await my_tg.get_updates(update_id = 872199521, limit = 5)
 
         # Show the response:
         print("SUMMARY:", tg_response.to_markdown(), "\n\n---\n\n")