tg-ringer 0.1.0__py3-none-any.whl

tg_ringer/__init__.py

@@ -0,0 +1,23 @@
+"""tg-ringer — ring and message any Telegram user from your own account (userbot).
+
+Account-to-account (MTProto), not a bot. The userbot places a real private
+Telegram call so the target's phone *rings* (use as an urgent alert), or sends
+a direct message.
+
+Basic use:
+
+    import asyncio
+    from tg_ringer import TgCaller
+
+    async def main():
+        async with TgCaller(api_id, api_hash, "userbot") as tg:
+            await tg.ring("+15551234567", seconds=20)
+            await tg.message("+15551234567", "heads up")
+
+    asyncio.run(main())
+"""
+
+from .client import TgCaller
+
+__all__ = ["TgCaller"]
+__version__ = "0.1.0"

tg_ringer/cli.py

@@ -0,0 +1,154 @@
+"""Command-line interface for tg-ringer.
+
+Commands:
+    tg-ringer login                 one-time interactive login (phone + code)
+    tg-ringer call  TARGET [-s N]   ring a user/number for N seconds
+    tg-ringer msg   TARGET TEXT     send a direct message
+    tg-ringer whoami                show the logged-in userbot account
+
+Config (env vars, or ~/.config/tg-ringer/config as KEY=VALUE lines):
+    TG_API_ID      required
+    TG_API_HASH    required
+    TG_SESSION     session file path (default ~/.config/tg-ringer/userbot)
+    TG_TARGET      default target for call/msg when none is given
+    RING_SECONDS   default ring duration (default 20)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+CONFIG_DIR = Path(
+    os.environ.get("TG_RINGER_HOME", Path.home() / ".config" / "tg-ringer")
+)
+CONFIG_FILE = CONFIG_DIR / "config"
+
+
+def _load_config() -> None:
+    """Load KEY=VALUE lines from the config file into os.environ (no override)."""
+    if not CONFIG_FILE.exists():
+        return
+    for line in CONFIG_FILE.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        os.environ.setdefault(key.strip(), val.strip().strip('"').strip("'"))
+
+
+def _creds() -> tuple[int, str]:
+    _load_config()
+    try:
+        return int(os.environ["TG_API_ID"]), os.environ["TG_API_HASH"]
+    except KeyError:
+        sys.exit(
+            "missing TG_API_ID / TG_API_HASH (env or config file). "
+            "Get them at https://my.telegram.org"
+        )
+
+
+def _session() -> str:
+    sess = os.environ.get("TG_SESSION")
+    if sess:
+        return sess
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    return str(CONFIG_DIR / "userbot")
+
+
+def _target(arg: str | None) -> str:
+    t = arg or os.environ.get("TG_TARGET")
+    if not t:
+        sys.exit("no target: pass one or set TG_TARGET")
+    return t
+
+
+def cmd_login(_args) -> None:
+    # Telethon's sync context manager runs the interactive login (phone, code,
+    # optional 2FA password) via stdin prompts.
+    from telethon.sync import TelegramClient
+
+    api_id, api_hash = _creds()
+    with TelegramClient(_session(), api_id, api_hash) as client:
+        me = client.get_me()
+        print(f"Logged in as {me.first_name} (id {me.id}, @{me.username})")
+        print(f"Session: {_session()}.session")
+
+
+def _run(coro):
+    from .client import TgCaller
+
+    api_id, api_hash = _creds()
+
+    async def runner():
+        async with TgCaller(api_id, api_hash, _session()) as tg:
+            return await coro(tg)
+
+    return asyncio.run(runner())
+
+
+def cmd_call(args) -> None:
+    target = _target(args.target)
+    seconds = args.seconds or int(os.environ.get("RING_SECONDS", "20"))
+
+    async def go(tg):
+        print(f"ringing {target} for {seconds}s ...")
+        cid = await tg.ring(target, seconds=seconds)
+        print(f"done (call id {cid})")
+
+    _run(go)
+
+
+def cmd_msg(args) -> None:
+    target = _target(args.target)
+    text = " ".join(args.text) if args.text else sys.stdin.read()
+
+    async def go(tg):
+        mid = await tg.message(target, text)
+        print(f"sent (msg id {mid})")
+
+    _run(go)
+
+
+def cmd_whoami(_args) -> None:
+    async def go(tg):
+        me = await tg.whoami()
+        print(f"{me.first_name} (id {me.id}, @{me.username})")
+
+    _run(go)
+
+
+def main(argv=None) -> None:
+    p = argparse.ArgumentParser(
+        prog="tg-ringer",
+        description="Ring/message Telegram users from your own account.",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("login", help="one-time interactive login").set_defaults(
+        func=cmd_login
+    )
+
+    pc = sub.add_parser("call", help="ring a user/number")
+    pc.add_argument("target", nargs="?", help="username, id, or +phone")
+    pc.add_argument("-s", "--seconds", type=int, help="ring duration")
+    pc.set_defaults(func=cmd_call)
+
+    pm = sub.add_parser("msg", help="send a direct message")
+    pm.add_argument("target", help="username, id, or +phone")
+    pm.add_argument("text", nargs="*", help="message text (or pipe via stdin)")
+    pm.set_defaults(func=cmd_msg)
+
+    sub.add_parser("whoami", help="show logged-in account").set_defaults(
+        func=cmd_whoami
+    )
+
+    args = p.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

tg_ringer/client.py

@@ -0,0 +1,117 @@
+"""Core async client: resolve targets, ring (private call), and message."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import secrets
+
+from telethon import TelegramClient
+from telethon.tl.functions.contacts import ImportContactsRequest
+from telethon.tl.functions.messages import GetDhConfigRequest
+from telethon.tl.functions.phone import DiscardCallRequest, RequestCallRequest
+from telethon.tl.types import (
+    InputPhoneCall,
+    InputPhoneContact,
+    PhoneCallDiscardReasonHangup,
+    PhoneCallProtocol,
+)
+
+
+class TgCaller:
+    """Userbot wrapper around Telethon for ringing and messaging users.
+
+    Args:
+        api_id: Telegram API id (https://my.telegram.org).
+        api_hash: Telegram API hash.
+        session: Telethon session name or path (a ``.session`` file).
+    """
+
+    def __init__(self, api_id: int, api_hash: str, session: str = "tgcaller"):
+        self.client = TelegramClient(session, api_id, api_hash)
+
+    async def __aenter__(self) -> TgCaller:
+        await self.client.connect()
+        if not await self.client.is_user_authorized():
+            raise RuntimeError("session not authorized — run `tg-ringer login` first")
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.client.disconnect()
+
+    async def resolve(self, target):
+        """Resolve a username, numeric id, or +phone number to an entity.
+
+        A ``+phone`` is imported as a temporary contact so it can be reached;
+        this is what lets you ring a number you have not chatted with before.
+        """
+        if isinstance(target, str) and target.startswith("+"):
+            res = await self.client(
+                ImportContactsRequest(
+                    [
+                        InputPhoneContact(
+                            client_id=0,
+                            phone=target,
+                            first_name="alert",
+                            last_name="target",
+                        )
+                    ]
+                )
+            )
+            if not res.users:
+                raise ValueError(f"{target} is not on Telegram / not resolvable")
+            return res.users[0]
+        return await self.client.get_input_entity(target)
+
+    async def ring(self, target, seconds: int = 20) -> int:
+        """Place a private call so ``target``'s phone rings, then hang up.
+
+        No audio is streamed — the *ring* is the alert. Returns the call id.
+        """
+        peer = await self.resolve(target)
+
+        dh = await self.client(GetDhConfigRequest(version=0, random_length=256))
+        p = int.from_bytes(dh.p, "big")
+        g = dh.g
+        a = int.from_bytes(secrets.token_bytes(256), "big") % p
+        g_a = pow(g, a, p)
+        g_a_hash = hashlib.sha256(g_a.to_bytes(256, "big")).digest()
+
+        protocol = PhoneCallProtocol(
+            min_layer=65,
+            max_layer=92,
+            udp_p2p=True,
+            udp_reflector=True,
+            library_versions=["4.0.0"],
+        )
+        res = await self.client(
+            RequestCallRequest(
+                user_id=peer,
+                random_id=secrets.randbelow(2**31),
+                g_a_hash=g_a_hash,
+                protocol=protocol,
+            )
+        )
+        call = res.phone_call
+        try:
+            await asyncio.sleep(seconds)
+        finally:
+            await self.client(
+                DiscardCallRequest(
+                    peer=InputPhoneCall(id=call.id, access_hash=call.access_hash),
+                    duration=0,
+                    reason=PhoneCallDiscardReasonHangup(),
+                    connection_id=0,
+                )
+            )
+        return call.id
+
+    async def message(self, target, text: str) -> int:
+        """Send a direct message to ``target``. Returns the message id."""
+        peer = await self.resolve(target)
+        msg = await self.client.send_message(peer, text)
+        return msg.id
+
+    async def whoami(self):
+        """Return the logged-in userbot account (Telethon User)."""
+        return await self.client.get_me()

tg_ringer-0.1.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: tg-ringer
+Version: 0.1.0
+Summary: Ring (call) and message any Telegram user from your own account — urgent alerts via a real Telegram call.
+Project-URL: Homepage, https://github.com/jdp5949/tg-ringer
+Project-URL: Documentation, https://jdp5949.github.io/tg-ringer/
+Project-URL: Repository, https://github.com/jdp5949/tg-ringer
+Project-URL: Issues, https://github.com/jdp5949/tg-ringer/issues
+Author: jdp5949
+License: MIT
+License-File: LICENSE
+Keywords: alert,call,mtproto,notification,telegram,telethon,userbot
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.9
+Requires-Dist: telethon<2,>=1.36
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tg-ringer
+
+Ring (call) and message **any Telegram user from your own account** — a lightweight
+[Telethon](https://github.com/LonamiWebs/Telethon) userbot for **urgent alerts**.
+
+It places a real **private Telegram call** so the target's phone *rings* (no audio
+is streamed — the ring itself is the alert), then hangs up. It can also send direct
+account-to-account messages.
+
+> **This is a userbot (your real account), not a bot.** That is the point — bots
+> cannot place calls. See [⚠️ ToS & bans](#️-tos--bans) before using.
+
+---
+
+## When to use it
+
+| You want… | Use this? |
+|-----------|-----------|
+| Phone to **ring** on a critical event (build failed, server down, prod alert) | ✅ yes |
+| A free alternative to paid call APIs, and you already live in Telegram | ✅ yes |
+| Account-to-account DM from a script (faster than Bot API on a warm connection) | ✅ yes |
+| Spoken/TTS audio in the call | ❌ no — ring only (see [limitations](#limitations)) |
+| Reach someone with **no internet** (real cellular call) | ❌ no — Telegram is VoIP; use Twilio/PSTN |
+| Mass messaging / spam | ❌ absolutely not — instant ban |
+
+---
+
+## Install
+
+```bash
+pip install tg-ringer
+```
+
+Requires Python 3.9+.
+
+---
+
+## Setup (one time)
+
+1. **Get API credentials** at <https://my.telegram.org> → *API development tools* →
+   create an app. Copy the **`api_id`** (number) and **`api_hash`** (string).
+
+2. **Configure.** Either export env vars or write a config file:
+
+   ```bash
+   mkdir -p ~/.config/tg-ringer
+   cat > ~/.config/tg-ringer/config <<'EOF'
+   TG_API_ID=1234567
+   TG_API_HASH=0123456789abcdef0123456789abcdef
+   TG_TARGET=+15551234567      # optional default target
+   RING_SECONDS=20             # optional
+   EOF
+   ```
+
+3. **Log in** (interactive — sends a code to your Telegram app):
+
+   ```bash
+   tg-ringer login
+   ```
+
+   Enter the **userbot account's** phone number, then the login code (delivered
+   *inside Telegram*, not SMS), and a 2FA password if you have one. This creates a
+   session file so future calls run unattended.
+
+> Use a **separate account** as the userbot — not the one you want to ring. You
+> cannot call yourself.
+
+---
+
+## CLI usage
+
+```bash
+# Ring a number (or @username, or numeric id) — phone rings, then hangs up
+tg-ringer call +15551234567
+tg-ringer call @someuser --seconds 30
+tg-ringer call                       # uses TG_TARGET
+
+# Send a direct message
+tg-ringer msg +15551234567 "deploy finished"
+echo "piped body" | tg-ringer msg @someuser
+
+# Who am I logged in as?
+tg-ringer whoami
+```
+
+### In scripts
+
+```bash
+long_task && tg-ringer msg "$ALERT" "✅ done" || tg-ringer call "$ALERT"
+```
+
+---
+
+## Library usage
+
+```python
+import asyncio
+from tg_ringer import TgCaller
+
+async def main():
+    async with TgCaller(api_id=1234567, api_hash="...", session="userbot") as tg:
+        await tg.ring("+15551234567", seconds=20)     # phone rings 20s
+        await tg.message("+15551234567", "heads up")   # direct message
+
+asyncio.run(main())
+```
+
+`TgCaller` methods (all async):
+
+| Method | Does |
+|--------|------|
+| `ring(target, seconds=20)` | Place a private call; phone rings then hangs up. Returns call id. |
+| `message(target, text)` | Send a direct message. Returns message id. |
+| `resolve(target)` | Resolve a `@username`, numeric id, or `+phone` to an entity. |
+| `whoami()` | Return the logged-in account. |
+
+`target` may be a `@username`, a numeric user id, or a `+E164` phone number. A
+phone number is imported as a temporary contact so it can be reached.
+
+---
+
+## Limitations
+
+- **Ring only, no audio.** Playing TTS/sound needs the full encrypted call to
+  connect (WebRTC/Opus). `pytgcalls` covers *group* voice chats, not private 1-to-1
+  calls; private-call audio needs the old `libtgvoip` stack (fragile). For a spoken
+  message, use a PSTN provider (e.g. Twilio).
+- **Internet required on the receiver.** Telegram calls are VoIP.
+- **Calls only land if Telegram lets them.** New accounts, and especially **VoIP
+  numbers**, hit anti-spam (`PeerFloodError`). Best results when caller and target
+  are **mutual contacts**.
+
+---
+
+## ⚠️ ToS & bans
+
+Automating a **user** account (userbot) is a **gray area** under Telegram's Terms of
+Service. Risks you accept by using this:
+
+- Accounts can be **limited or banned**, especially VoIP numbers, new accounts, or
+  any account making automated calls/messages to non-contacts.
+- Keep volume low. Make the caller and target **mutual contacts**. Do **not** spam.
+- Use a throwaway/secondary account as the userbot.
+
+You are responsible for how you use this. See `@SpamBot` in Telegram to check an
+account's restriction status.
+
+---
+
+## Security
+
+- Your `api_hash` and the `*.session` file grant **full access to the userbot
+  account**. Never commit or share them. The config and session live under
+  `~/.config/tg-ringer/` and are git-ignored in this repo.
+- Revoke a leaked session from any Telegram client: *Settings → Devices → Terminate*.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `PeerFloodError` | Account anti-spam limited. Make caller+target mutual contacts; check `@SpamBot`; wait; or use a non-VoIP number. |
+| `session not authorized` | Run `tg-ringer login`. |
+| Login code never arrives | It's delivered **in the Telegram app** ("Telegram" service chat), not SMS. The userbot number must be logged into a Telegram client. |
+| Target not on Telegram | `+phone` must belong to a Telegram account. |
+| No notification but message sent | Receiver chat is muted / OS notifications off. |
+
+---
+
+## License
+
+MIT © jdp5949

tg_ringer-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+tg_ringer/__init__.py,sha256=sStEUxNmsOR4VuIVKlzzqDUEYnVgEJDE7OR0GY2u1Hg,628
+tg_ringer/cli.py,sha256=NR_ZE3bQxnolrJeCNz6rzfwBDveHOentf4I_KBhfy5c,4436
+tg_ringer/client.py,sha256=8wlpGbvH83qXGwuQkEyBZH6TZ-r_owVnWNnr2Q_AIoM,4064
+tg_ringer-0.1.0.dist-info/METADATA,sha256=jSB8_Az5DiStFxL9FG-bpMNR92k3RwOqsTOhKR5JDts,6710
+tg_ringer-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tg_ringer-0.1.0.dist-info/entry_points.txt,sha256=yCbHVDpsOcf-xYAnb0hEoxXDC7bzMQoE84PylJqQGME,49
+tg_ringer-0.1.0.dist-info/licenses/LICENSE,sha256=1awIoOgnZD8e6oshrGpw5gImDnUr0uVgoZk4pKJCx2s,1064
+tg_ringer-0.1.0.dist-info/RECORD,,

tg_ringer-0.1.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

tg_ringer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tg-ringer = tg_ringer.cli:main

tg_ringer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jdp5949
+
+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.