telegram-tgcli 1.0.0__py3-none-any.whl

telegram_tgcli-1.0.0.dist-info/METADATA

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: telegram-tgcli
+Version: 1.0.0
+Summary: A powerful, feature-rich Telegram CLI and webhook daemon using Telethon
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: telethon>=1.35.0
+Description-Content-Type: text/markdown
+
+# tgcli
+
+A powerful, feature-rich Telegram CLI and webhook daemon built on top of Telethon.
+
+## Installation
+
+Install in editable mode or globally using `uv`:
+
+```bash
+uv tool install .
+```
+
+## Features
+
+- **Interactive Login**: `tgcli login`
+- **List Chats**: `tgcli chats [--limit LIMIT]`
+- **Send Messages / Media**:
+  - Text: `tgcli send --target TARGET --text "Hello"`
+  - Image/Video/Files: `tgcli send --target TARGET --file /path/to/image.jpg --caption "Beautiful sky"`
+  - Voice Notes: `tgcli send --target TARGET --file /path/to/audio.ogg --voice`
+- **Edit Messages**: `tgcli edit --target TARGET --message-id ID --text "New Text"`
+- **Delete Messages**: `tgcli delete --target TARGET --message-ids ID1 ID2`
+- **History**: `tgcli history --target TARGET [--limit LIMIT]`
+- **Members**: `tgcli members --target TARGET`
+- **Listen & Webhook Daemon**:
+  - Listens to incoming Telegram events and logs them as JSON.
+  - Optional `--webhook-url` to forward incoming messages (and download media automatically!) to an external webhook.
+  - `tgcli listen --webhook-url https://example.com/webhook`

telegram_tgcli-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+tgcli/__init__.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+tgcli/cli.py,sha256=RodEx6gVA_h9f1RULjWs02emOEn9RzsUezEb2PnXm-U,5962
+tgcli/client.py,sha256=icRgBA7Jt0lOXTEXWf1QwwIGQ9kYYlnOnNxCl5Kd1_w,6225
+tgcli/config.py,sha256=2pWUTEhRiLSD4INchLXlFp3_IEM6cJIetBwvHr3i30A,439
+tgcli/daemon.py,sha256=P0JxAibXPpV5Vz6jCxU-Q3Xd2Lg4Z20cnCKFCV88B3c,5610
+tgcli/stt.py,sha256=QbWWO95eKa8qrnqlTMZsyDKQ-Sbc5jxUEZeRc9YRL44,1016
+tgcli/webhooks.py,sha256=KN0I8QCDuZGVbj39jBgQVbOeRkflahksLMzuKaSYU5I,6178
+telegram_tgcli-1.0.0.dist-info/METADATA,sha256=wh5nEyqTmlGNR7G5_abAladc1U7IfZrCTSgYm9BX4N4,1388
+telegram_tgcli-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+telegram_tgcli-1.0.0.dist-info/entry_points.txt,sha256=bGOSON7FJm4Zpm7LTKiW4Hiq1rQoAfCm-FWRWxfH0mU,41
+telegram_tgcli-1.0.0.dist-info/licenses/LICENSE,sha256=KT8EI_4OumMSFsYqUD31iIudR2f0f_QL95LsOXnDlf4,1069
+telegram_tgcli-1.0.0.dist-info/RECORD,,

telegram_tgcli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

telegram_tgcli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tgcli = tgcli.cli:main

telegram_tgcli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Alrabeei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tgcli/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

tgcli/cli.py

@@ -0,0 +1,126 @@
+import sys
+import argparse
+import asyncio
+from .client import (
+    login_client,
+    list_chats,
+    send_message_or_file,
+    edit_message,
+    delete_messages,
+    get_history,
+    get_members
+)
+from .webhooks import run_listener
+from .daemon import (
+    daemon_install,
+    daemon_uninstall,
+    daemon_status,
+    daemon_logs
+)
+
+def main():
+    parser = argparse.ArgumentParser(description="Telegram CLI - Feature-rich Telegram Client & Webhook Daemon")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    
+    # login
+    subparsers.add_parser("login", help="Interactively log in to Telegram")
+    
+    # chats
+    chats_parser = subparsers.add_parser("chats", help="List recent chats/dialogs")
+    chats_parser.add_argument("--limit", type=int, default=20, help="Max chats to list (default: 20)")
+    
+    # send
+    send_parser = subparsers.add_parser("send", help="Send a message or file/media")
+    send_parser.add_argument("--target", required=True, help="Username, chat ID, or phone number")
+    send_parser.add_argument("--text", help="Text message content")
+    send_parser.add_argument("--file", help="Path to a file/media to send")
+    send_parser.add_argument("--caption", help="Caption to send with the file (overrides --text if both provided)")
+    send_parser.add_argument("--voice", action="store_true", help="Send the file as an audio voice note")
+    
+    # edit
+    edit_parser = subparsers.add_parser("edit", help="Edit an existing sent message")
+    edit_parser.add_argument("--target", required=True, help="Username, chat ID, or phone number")
+    edit_parser.add_argument("--message-id", required=True, type=int, help="ID of the message to edit")
+    edit_parser.add_argument("--text", required=True, help="New text content for the message")
+    
+    # delete
+    delete_parser = subparsers.add_parser("delete", help="Delete messages")
+    delete_parser.add_argument("--target", required=True, help="Username, chat ID, or phone number")
+    delete_parser.add_argument("--message-ids", required=True, nargs="+", help="One or more message IDs to delete (space-separated)")
+    
+    # history
+    history_parser = subparsers.add_parser("history", help="Retrieve message history")
+    history_parser.add_argument("--target", required=True, help="Username, chat ID, or phone number")
+    history_parser.add_argument("--limit", type=int, default=10, help="Number of messages to retrieve (default: 10)")
+    
+    # members
+    members_parser = subparsers.add_parser("members", help="Retrieve chat members/participants")
+    members_parser.add_argument("--target", required=True, help="Username, chat ID, or phone number")
+    
+    # listen (webhook daemon foreground)
+    listen_parser = subparsers.add_parser("listen", help="Run webhook daemon and listen for new messages")
+    listen_parser.add_argument("--webhook-url", help="URL to send HTTP POST webhook payloads to when messages are received")
+    listen_parser.add_argument("--webhook-header", action="append", help="Custom header in 'Name: Value' format (can be specified multiple times)")
+    listen_parser.add_argument("--verbose", action="store_true", help="Print debug information and full JSON payloads")
+    
+    # daemon (systemd management)
+    daemon_parser = subparsers.add_parser("daemon", help="Manage tgcli systemd background daemon")
+    daemon_subparsers = daemon_parser.add_subparsers(dest="daemon_command", required=True)
+    
+    # daemon install
+    install_parser = daemon_subparsers.add_parser("install", help="Install & start systemd user daemon")
+    install_parser.add_argument("--webhook-url", required=True, help="URL to send webhook payloads to")
+    install_parser.add_argument("--webhook-header", action="append", help="Custom header in 'Name: Value' format (can be specified multiple times)")
+    install_parser.add_argument("--verbose", action="store_true", help="Enable verbose/debug logging in daemon")
+    
+    # daemon uninstall
+    daemon_subparsers.add_parser("uninstall", help="Stop & remove systemd user daemon")
+    
+    # daemon status
+    daemon_subparsers.add_parser("status", help="Show daemon systemd status")
+    
+    # daemon logs
+    daemon_subparsers.add_parser("logs", help="Show recent daemon logs")
+    
+    args = parser.parse_args()
+    
+    try:
+        if args.command == "login":
+            asyncio.run(login_client())
+        elif args.command == "chats":
+            asyncio.run(list_chats(args.limit))
+        elif args.command == "send":
+            if not args.text and not args.file:
+                parser.error("At least one of --text or --file is required for send.")
+            asyncio.run(send_message_or_file(
+                target=args.target,
+                text=args.text,
+                file_path=args.file,
+                caption=args.caption,
+                voice=args.voice
+            ))
+        elif args.command == "edit":
+            asyncio.run(edit_message(args.target, args.message_id, args.text))
+        elif args.command == "delete":
+            asyncio.run(delete_messages(args.target, args.message_ids))
+        elif args.command == "history":
+            asyncio.run(get_history(args.target, args.limit))
+        elif args.command == "members":
+            asyncio.run(get_members(args.target))
+        elif args.command == "listen":
+            asyncio.run(run_listener(args.webhook_url, args.webhook_header, args.verbose))
+        elif args.command == "daemon":
+            if args.daemon_command == "install":
+                daemon_install(args.webhook_url, args.webhook_header, args.verbose)
+            elif args.daemon_command == "uninstall":
+                daemon_uninstall()
+            elif args.daemon_command == "status":
+                daemon_status()
+            elif args.daemon_command == "logs":
+                daemon_logs()
+    except KeyboardInterrupt:
+        print("\nExiting...")
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()

tgcli/client.py

@@ -0,0 +1,202 @@
+import sys
+import json
+from telethon import TelegramClient, utils
+from .config import API_ID, API_HASH, SESSION_PATH
+
+def get_client():
+    return TelegramClient(SESSION_PATH, API_ID, API_HASH)
+
+async def check_auth(client):
+    await client.connect()
+    if not await client.is_user_authorized():
+        print(json.dumps({"success": False, "error": "Not authorized. Run 'tgcli login' first."}, indent=2))
+        await client.disconnect()
+        sys.exit(1)
+
+async def login_client():
+    client = get_client()
+    print("Connecting to Telegram and starting interactive authorization...")
+    await client.start()
+    me = await client.get_me()
+    print(f"\nSuccessfully logged in as: {me.first_name} (@{me.username or 'No Username'}) [ID: {me.id}]")
+    await client.disconnect()
+
+async def list_chats(limit=20):
+    client = get_client()
+    await check_auth(client)
+    
+    chats_data = []
+    async for dialog in client.iter_dialogs(limit=limit):
+        entity = dialog.entity
+        entity_type = "user" if dialog.is_user else "group" if dialog.is_group else "channel" if dialog.is_channel else "unknown"
+        chats_data.append({
+            "id": dialog.id,
+            "name": dialog.name,
+            "username": getattr(entity, 'username', None),
+            "type": entity_type,
+            "unread_count": dialog.unread_count
+        })
+    print(json.dumps(chats_data, indent=2, ensure_ascii=False))
+    await client.disconnect()
+
+async def send_message_or_file(target, text=None, file_path=None, caption=None, voice=False):
+    client = get_client()
+    await check_auth(client)
+    
+    try:
+        resolved_target = int(target)
+    except ValueError:
+        resolved_target = target
+        
+    try:
+        if file_path:
+            # Send file (image, video, document, or voice note)
+            msg = await client.send_file(
+                resolved_target,
+                file_path,
+                caption=caption or text,
+                voice_note=voice
+            )
+            media_type = "voice" if voice else "file"
+        else:
+            # Send text message
+            msg = await client.send_message(resolved_target, text)
+            media_type = None
+
+        print(json.dumps({
+            "success": True,
+            "message_id": msg.id,
+            "to": target,
+            "text": text or caption,
+            "media_type": media_type
+        }, indent=2))
+    except Exception as e:
+        print(json.dumps({
+            "success": False,
+            "error": str(e)
+        }, indent=2))
+    await client.disconnect()
+
+async def edit_message(target, message_id, text):
+    client = get_client()
+    await check_auth(client)
+    
+    try:
+        resolved_target = int(target)
+    except ValueError:
+        resolved_target = target
+        
+    try:
+        msg = await client.edit_message(resolved_target, int(message_id), text)
+        print(json.dumps({
+            "success": True,
+            "message_id": msg.id,
+            "to": target,
+            "text": text
+        }, indent=2))
+    except Exception as e:
+        print(json.dumps({
+            "success": False,
+            "error": str(e)
+        }, indent=2))
+    await client.disconnect()
+
+async def delete_messages(target, message_ids):
+    client = get_client()
+    await check_auth(client)
+    
+    try:
+        resolved_target = int(target)
+    except ValueError:
+        resolved_target = target
+        
+    try:
+        # Convert list of IDs to integers
+        ids = [int(x) for x in message_ids]
+        await client.delete_messages(resolved_target, ids)
+        print(json.dumps({
+            "success": True,
+            "deleted_ids": ids,
+            "from": target
+        }, indent=2))
+    except Exception as e:
+        print(json.dumps({
+            "success": False,
+            "error": str(e)
+        }, indent=2))
+    await client.disconnect()
+
+async def get_history(target, limit=10):
+    client = get_client()
+    await check_auth(client)
+    
+    try:
+        resolved_target = int(target)
+    except ValueError:
+        resolved_target = target
+        
+    try:
+        messages = []
+        async for msg in client.iter_messages(resolved_target, limit=limit):
+            sender = await msg.get_sender()
+            sender_name = utils.get_display_name(sender) if sender else "Unknown"
+            
+            # Check for media
+            media_type = None
+            if msg.media:
+                if msg.photo:
+                    media_type = "photo"
+                elif msg.voice:
+                    media_type = "voice"
+                elif msg.video:
+                    media_type = "video"
+                elif msg.audio:
+                    media_type = "audio"
+                elif msg.document:
+                    media_type = "document"
+                else:
+                    media_type = "other"
+
+            messages.append({
+                "id": msg.id,
+                "date": msg.date.isoformat(),
+                "sender_id": msg.sender_id,
+                "sender_name": sender_name,
+                "text": msg.text or "",
+                "media_type": media_type
+            })
+        print(json.dumps(messages, indent=2, ensure_ascii=False))
+    except Exception as e:
+        print(json.dumps({
+            "success": False,
+            "error": str(e)
+        }, indent=2))
+    await client.disconnect()
+
+async def get_members(target):
+    client = get_client()
+    await check_auth(client)
+    
+    try:
+        resolved_target = int(target)
+    except ValueError:
+        resolved_target = target
+        
+    try:
+        members = []
+        async for user in client.iter_participants(resolved_target):
+            members.append({
+                "id": user.id,
+                "first_name": user.first_name,
+                "last_name": user.last_name or "",
+                "username": user.username or "",
+                "phone": user.phone or "",
+                "is_bot": user.bot
+            })
+        print(json.dumps(members, indent=2, ensure_ascii=False))
+    except Exception as e:
+        print(json.dumps({
+            "success": False,
+            "error": str(e)
+        }, indent=2))
+    await client.disconnect()

tgcli/config.py

@@ -0,0 +1,10 @@
+import os
+
+API_ID = int(os.getenv("TG_API_ID", "32206730"))
+API_HASH = os.getenv("TG_API_HASH", "c3b333fd816ba995bc0fcf685e3fde60")
+SESSION_PATH = os.getenv("TG_SESSION_PATH", os.path.expanduser("~/.tgcli/tg_session"))
+DOWNLOADS_DIR = os.getenv("TG_DOWNLOADS_DIR", os.path.expanduser("~/.tgcli/downloads"))
+
+# Create necessary directories
+os.makedirs(os.path.dirname(SESSION_PATH), exist_ok=True)
+os.makedirs(DOWNLOADS_DIR, exist_ok=True)

tgcli/daemon.py

@@ -0,0 +1,171 @@
+import os
+import sys
+import shutil
+import subprocess
+import json
+
+SERVICE_NAME = "tgcli-daemon"
+USER_SERVICE_DIR = os.path.expanduser("~/.config/systemd/user")
+SERVICE_FILE_PATH = os.path.join(USER_SERVICE_DIR, f"{SERVICE_NAME}.service")
+
+def check_systemctl():
+    if not shutil.which("systemctl"):
+        return False
+    return True
+
+def run_systemctl_cmd(args):
+    try:
+        result = subprocess.run(
+            ["systemctl", "--user"] + args,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return True, result.stdout, result.stderr
+    except subprocess.CalledProcessError as e:
+        return False, e.stdout, e.stderr
+
+def daemon_install(webhook_url, webhook_headers=None, verbose=False):
+    if not check_systemctl():
+        print(json.dumps({"success": False, "error": "systemctl not found. Is systemd installed?"}, indent=2))
+        return
+
+    # Find the absolute path to the tgcli binary
+    tgcli_path = shutil.which("tgcli")
+    if not tgcli_path:
+        # Fallback to sys.argv[0] if not found in PATH
+        tgcli_path = os.path.abspath(sys.argv[0])
+    
+    verbose_flag = "--verbose" if verbose else ""
+    
+    # Process custom headers into command arguments
+    header_args = []
+    if webhook_headers:
+        for header_str in webhook_headers:
+            header_args.append(f'--webhook-header "{header_str}"')
+    header_str = " ".join(header_args)
+    
+    # Construct service contents
+    service_content = f"""[Unit]
+Description=Telegram CLI Webhook Daemon
+After=network.target
+
+[Service]
+ExecStart={tgcli_path} listen --webhook-url {webhook_url} {header_str} {verbose_flag}
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+"""
+    
+    try:
+        os.makedirs(USER_SERVICE_DIR, exist_ok=True)
+        with open(SERVICE_FILE_PATH, "w") as f:
+            f.write(service_content)
+        
+        # Reload daemon
+        success, out, err = run_systemctl_cmd(["daemon-reload"])
+        if not success:
+            raise Exception(f"daemon-reload failed: {err}")
+            
+        # Enable and start service
+        success, out, err = run_systemctl_cmd(["enable", f"{SERVICE_NAME}.service"])
+        if not success:
+            raise Exception(f"enable failed: {err}")
+            
+        success, out, err = run_systemctl_cmd(["start", f"{SERVICE_NAME}.service"])
+        if not success:
+            raise Exception(f"start failed: {err}")
+            
+        print(json.dumps({
+            "success": True,
+            "message": "tgcli daemon installed and started successfully!",
+            "service": SERVICE_NAME,
+            "path": SERVICE_FILE_PATH,
+            "webhook_url": webhook_url,
+            "webhook_headers": webhook_headers or [],
+            "executable": tgcli_path
+        }, indent=2))
+        
+    except Exception as e:
+        print(json.dumps({"success": False, "error": str(e)}, indent=2))
+
+def daemon_uninstall():
+    if not check_systemctl():
+        print(json.dumps({"success": False, "error": "systemctl not found."}, indent=2))
+        return
+        
+    try:
+        # Stop service
+        run_systemctl_cmd(["stop", f"{SERVICE_NAME}.service"])
+        # Disable service
+        run_systemctl_cmd(["disable", f"{SERVICE_NAME}.service"])
+        
+        # Remove file
+        if os.path.exists(SERVICE_FILE_PATH):
+            os.remove(SERVICE_FILE_PATH)
+            
+        # Reload daemon
+        run_systemctl_cmd(["daemon-reload"])
+        
+        print(json.dumps({
+            "success": True,
+            "message": "tgcli daemon uninstalled and removed successfully!"
+        }, indent=2))
+    except Exception as e:
+        print(json.dumps({"success": False, "error": str(e)}, indent=2))
+
+def daemon_status():
+    if not check_systemctl():
+        print(json.dumps({"success": False, "error": "systemctl not found."}, indent=2))
+        return
+        
+    # Check if file exists
+    if not os.path.exists(SERVICE_FILE_PATH):
+        print(json.dumps({
+            "success": True,
+            "installed": False,
+            "status": "not installed"
+        }, indent=2))
+        return
+        
+    # Run show and is-active
+    success_active, out_active, _ = run_systemctl_cmd(["is-active", f"{SERVICE_NAME}.service"])
+    success_enabled, out_enabled, _ = run_systemctl_cmd(["is-enabled", f"{SERVICE_NAME}.service"])
+    
+    # Read properties for details
+    _, out_show, _ = run_systemctl_cmd(["show", f"{SERVICE_NAME}.service", "--property=ActiveState,SubState,LoadState,UnitFileState,MainPID"])
+    
+    props = {}
+    for line in out_show.strip().split("\n"):
+        if "=" in line:
+            k, v = line.split("=", 1)
+            props[k] = v
+            
+    print(json.dumps({
+        "success": True,
+        "installed": True,
+        "service": SERVICE_NAME,
+        "active_state": props.get("ActiveState", "unknown"),
+        "sub_state": props.get("SubState", "unknown"),
+        "enabled": out_enabled.strip() == "enabled",
+        "load_state": props.get("LoadState", "unknown"),
+        "main_pid": int(props.get("MainPID", "0")),
+        "unit_file_path": SERVICE_FILE_PATH
+    }, indent=2))
+
+def daemon_logs():
+    try:
+        # Use journalctl to get recent daemon logs
+        result = subprocess.run(
+            ["journalctl", "--user", "-u", SERVICE_NAME, "-n", "30", "--no-pager"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        print(result.stdout)
+    except Exception as e:
+        print(f"Error reading daemon logs: {e}")

tgcli/stt.py

@@ -0,0 +1,29 @@
+import logging
+
+logger = logging.getLogger("tgcli-stt")
+
+# Cached model instance
+_whisper_model = None
+
+def transcribe_audio(file_path):
+    global _whisper_model
+    try:
+        import whisper
+    except ImportError:
+        logger.debug("openai-whisper is not installed in the active environment. Skipping transcription.")
+        return None
+
+    try:
+        if _whisper_model is None:
+            logger.info("Loading local Whisper 'tiny' model for speech-to-text...")
+            # 'tiny' is extremely fast, low RAM/CPU usage, and perfect for short voice messages.
+            _whisper_model = whisper.load_model("tiny")
+        
+        logger.info(f"Transcribing voice file: {file_path}")
+        result = _whisper_model.transcribe(file_path)
+        transcription = result.get("text", "").strip()
+        logger.info(f"Successfully transcribed: \"{transcription}\"")
+        return transcription
+    except Exception as e:
+        logger.error(f"Error during audio transcription: {e}")
+        return None

tgcli/webhooks.py

@@ -0,0 +1,144 @@
+import os
+import sys
+import json
+import logging
+import httpx
+from datetime import datetime
+from telethon import events, utils
+from .config import DOWNLOADS_DIR
+from .client import get_client, check_auth
+from .stt import transcribe_audio
+
+# Set up logging for the webhook daemon
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    handlers=[logging.StreamHandler(sys.stdout)]
+)
+logger = logging.getLogger("tgcli-webhook")
+
+async def forward_webhook(url, payload, headers=None):
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.post(url, json=payload, headers=headers, timeout=10.0)
+            if response.status_code >= 200 and response.status_code < 300:
+                logger.info(f"Webhook forwarded successfully! Status: {response.status_code}")
+            else:
+                logger.error(f"Webhook forward failed with status code {response.status_code}: {response.text}")
+    except Exception as e:
+        logger.error(f"Failed to forward webhook to {url}: {e}")
+
+async def run_listener(webhook_url=None, webhook_headers=None, verbose=False):
+    if verbose:
+        logger.setLevel(logging.DEBUG)
+        
+    client = get_client()
+    await check_auth(client)
+    
+    # Parse custom headers
+    parsed_headers = {}
+    if webhook_headers:
+        for header_str in webhook_headers:
+            if ":" in header_str:
+                k, v = header_str.split(":", 1)
+                parsed_headers[k.strip()] = v.strip()
+                logger.info(f"Configured custom webhook header -> {k.strip()}: [REDACTED]")
+    
+    me = await client.get_me()
+    logger.info(f"Logged in as: {me.first_name} (@{me.username or 'No Username'}) [ID: {me.id}]")
+    logger.info("Webhook daemon listening for new messages...")
+    if webhook_url:
+        logger.info(f"Webhooks will be emitted to: {webhook_url}")
+    else:
+        logger.info("No webhook URL provided. Messages will be printed as JSON to console.")
+
+    @client.on(events.NewMessage)
+    async def handler(event):
+        try:
+            msg = event.message
+            chat = await event.get_chat()
+            sender = await event.get_sender()
+            
+            # Construct sender details
+            sender_id = msg.sender_id
+            sender_info = {
+                "id": sender_id,
+                "first_name": getattr(sender, "first_name", ""),
+                "last_name": getattr(sender, "last_name", ""),
+                "username": getattr(sender, "username", ""),
+                "phone": getattr(sender, "phone", ""),
+                "display_name": utils.get_display_name(sender) if sender else "Unknown"
+            }
+            
+            # Construct chat details
+            chat_type = "user" if event.is_private else "group" if event.is_group else "channel" if event.is_channel else "unknown"
+            chat_info = {
+                "id": event.chat_id,
+                "name": utils.get_display_name(chat) if chat else "Unknown",
+                "username": getattr(chat, "username", ""),
+                "type": chat_type
+            }
+            
+            # Media info & Download
+            media_info = {"present": False, "type": None, "local_path": None, "transcription": None}
+            if msg.media:
+                media_info["present"] = True
+                if msg.photo:
+                    media_info["type"] = "photo"
+                elif msg.voice:
+                    media_info["type"] = "voice"
+                elif msg.video:
+                    media_info["type"] = "video"
+                elif msg.audio:
+                    media_info["type"] = "audio"
+                elif msg.document:
+                    media_info["type"] = "document"
+                else:
+                    media_info["type"] = "other"
+                
+                try:
+                    logger.info(f"Downloading incoming {media_info['type']} media from message ID {msg.id}...")
+                    # Download media to the configured downloads directory
+                    local_path = await msg.download_media(file=DOWNLOADS_DIR)
+                    if local_path:
+                        media_info["local_path"] = os.path.abspath(local_path)
+                        logger.info(f"Downloaded media saved to: {media_info['local_path']}")
+                        
+                        # Auto-transcribe if it's a voice note or audio file
+                        if media_info["type"] in ["voice", "audio"]:
+                            transcription = transcribe_audio(media_info["local_path"])
+                            if transcription:
+                                media_info["transcription"] = transcription
+                except Exception as ex:
+                    logger.error(f"Error downloading/transcribing media: {ex}")
+            
+            # Build full message payload
+            payload = {
+                "event": "new_message",
+                "timestamp": datetime.utcnow().isoformat() + "Z",
+                "message": {
+                    "id": msg.id,
+                    "text": msg.text or "",
+                    "date": msg.date.isoformat() if msg.date else "",
+                    "reply_to_msg_id": msg.reply_to_msg_id
+                },
+                "chat": chat_info,
+                "sender": sender_info,
+                "media": media_info
+            }
+            
+            # Print to stdout/logger
+            logger.info(f"New Message Recieved from {sender_info['display_name']} in {chat_info['name']}: {msg.text or '[Media]'}")
+            if verbose or not webhook_url:
+                print(json.dumps(payload, indent=2, ensure_ascii=False))
+                
+            # If webhook URL is set, emit webhook
+            if webhook_url:
+                # Forward using background asyncio task so we don't block the listener loop
+                client.loop.create_task(forward_webhook(webhook_url, payload, parsed_headers))
+                
+        except Exception as e:
+            logger.error(f"Error in message handler: {e}")
+
+    # Run the client until disconnected
+    await client.run_until_disconnected()