|
1 | | -# 🤖 Telegram Auto Sign |
| 1 | +# TelegramAutoSignBot |
2 | 2 |
|
| 3 | +[简体中文](README_CN.md) |
3 | 4 |
|
4 | | -This is a Telegram auto sign-in bot powered by GitHub Actions and Telethon. It can send scheduled sign-in commands to multiple bots. |
| 5 | +[](https://github.com/Pigbibi/TelegramAutoSignBot/actions/workflows/main.yml) |
| 6 | +[](LICENSE) |
5 | 7 |
|
6 | | -An automated daily sign-in script for Telegram bots, powered by GitHub Actions and Python (Telethon). It uses your personal account (Userbot) to send configurable sign-in commands to specified Telegram bots daily. |
| 8 | +Use a Telegram user account to send scheduled commands to configured bots with |
| 9 | +Telethon and GitHub Actions. |
7 | 10 |
|
8 | | -## ✨ Core Features |
9 | | -* **☁️ Zero-Cost Deployment**: Runs entirely on GitHub Actions. No need for a local server or VPS. |
10 | | -* **👥 Multi-Bot Support**: Sends sign-in commands to multiple bots sequentially. Each bot can use its own command (e.g. `/qd`, `sign`) via a single combined `BOT_CONFIG` variable. |
11 | | -* **🎲 Smart Anti-Ban System**: Built-in 1~20 minutes randomized startup delay and random pauses between messages to prevent triggering Telegram's spam filters. |
12 | | -* **📝 Auto-Log Keepalive**: Automatically writes sign-in results to `checkin.log` and pushes it to the repository after each run. This perfectly bypasses GitHub Actions' 60-day inactivity suspension rule. |
| 11 | +## Important limitation |
13 | 12 |
|
14 | | -## 🚀 Deployment Guide |
| 13 | +This project automates a personal Telegram account, not a Bot API account. A |
| 14 | +Telethon session string grants account access and must be protected like a |
| 15 | +password. Random delays do not guarantee that Telegram or a destination bot |
| 16 | +will permit the automation. Use a private deployment, keep the target list |
| 17 | +small, and follow Telegram's terms and each bot's rules. |
15 | 18 |
|
16 | | -### Step 1: Get API Credentials |
17 | | -1. Log in to the [Telegram API Development Tools](https://my.telegram.org/). |
18 | | -2. Create a new application. |
19 | | -3. Note down your `App api_id` and `App api_hash`. |
| 19 | +## How it works |
20 | 20 |
|
21 | | -### Step 2: Get Session String |
22 | | -Install the dependency (`pip install telethon`) on your local machine and run a script to generate your session string. |
23 | | -> ⚠️ **WARNING**: Treat your Session String like a password. NEVER share it publicly! |
| 21 | +```text |
| 22 | +GitHub Actions daily schedule |
| 23 | + │ |
| 24 | + ▼ |
| 25 | +Telethon opens the configured user session |
| 26 | + │ |
| 27 | + ▼ |
| 28 | +commands sent to BOT_CONFIG targets in order |
| 29 | + │ |
| 30 | + ▼ |
| 31 | +run record appended on the logs branch |
| 32 | +``` |
24 | 33 |
|
25 | | -### Step 3: Configure GitHub Repository Secrets |
26 | | -1. Create a **Private** repository (Highly recommended for security). |
27 | | -2. Go to `Settings` -> `Secrets and variables` -> `Actions`, and under the **Secrets** tab add: |
28 | | - * `API_ID`: Your API ID (Numbers only). |
29 | | - * `API_HASH`: Your API Hash string. |
30 | | - * `SESSION_STRING`: The extremely long session string generated in Step 2. |
| 34 | +The workflow starts at `00:00 UTC` every day. The script waits a random 1–5 |
| 35 | +minutes before connecting and 2–5 seconds between targets. These delays reduce |
| 36 | +burst traffic but are not an anti-abuse guarantee. |
31 | 37 |
|
32 | | -### Step 4: Configure GitHub Actions Variables |
33 | | -1. Still under `Settings` -> `Secrets and variables` -> `Actions`, switch to the **Variables** tab. |
34 | | -2. Add a new variable: |
35 | | - * `BOT_CONFIG`: Mapping of bot usernames and sign-in commands in a single string. |
| 38 | +## Configuration |
36 | 39 |
|
37 | | - Format: comma-separated entries, each entry is `bot_username:command`. The command is sent exactly as configured, so add `/` yourself only when the target bot requires it. |
38 | | - Examples: |
39 | | - * `@bot1:/qd,@bot2:sign` |
40 | | - * `@bot1:/qd,@bot2:sign,@bot3` (bot3 uses default `/qd` since no command is specified) |
| 40 | +Add these repository secrets: |
41 | 41 |
|
42 | | -### Step 5: Grant Action Permissions |
43 | | -To allow the script to push the log file back to the repository: |
44 | | -1. Go to `Settings` -> `Actions` -> `General`. |
45 | | -2. Scroll down to **Workflow permissions**. |
46 | | -3. Select **Read and write permissions** and click `Save`. |
| 42 | +| Secret | Purpose | |
| 43 | +| --- | --- | |
| 44 | +| `API_ID` | Telegram application ID from `my.telegram.org` | |
| 45 | +| `API_HASH` | Telegram application hash | |
| 46 | +| `SESSION_STRING` | Telethon StringSession credential for the user account | |
47 | 47 |
|
48 | | -### Step 6: First Run & Test |
49 | | -Go to the **Actions** tab, select the `Telegram Auto Sign` workflow on the left, and click `Run workflow` to test it manually. If successful, your account will send the commands, and a log file will appear in your repository! |
| 48 | +Add this repository variable: |
50 | 49 |
|
51 | | ---- |
| 50 | +| Variable | Format | |
| 51 | +| --- | --- | |
| 52 | +| `BOT_CONFIG` | Comma-separated `bot_username:command` entries | |
52 | 53 |
|
53 | | -## ⏱️ Schedule Modification |
54 | | -The default trigger time is **00:00 UTC daily**. |
55 | | -To modify this, edit the cron expression in `.github/workflows/main.yml`. |
| 54 | +Examples: |
56 | 55 |
|
57 | | -## 📄 License |
58 | | -This project is licensed under the MIT License. See the `LICENSE` file for details. |
| 56 | +```text |
| 57 | +@bot1:/qd,@bot2:sign |
| 58 | +@bot1:/qd,@bot2:sign,@bot3 |
| 59 | +``` |
59 | 60 |
|
60 | | -## ⚠️ Disclaimer |
61 | | -This script is for educational and automated testing purposes only. Do not use it for high-frequency spamming or violating Telegram's Terms of Service. The user bears all responsibility for any account restrictions or bans caused by API abuse. |
| 61 | +An entry without a command uses `/qd`. Commands are otherwise sent exactly as |
| 62 | +configured; the script does not add a leading slash. |
| 63 | + |
| 64 | +## Create a session string |
| 65 | + |
| 66 | +Install Telethon on a trusted local machine and use your own Telegram API |
| 67 | +credentials to create a StringSession. Never run a session-generation tool from |
| 68 | +an untrusted repository or website. |
| 69 | + |
| 70 | +After generating the value, store it only as the `SESSION_STRING` Actions |
| 71 | +secret. Do not paste it into workflow files, issues, logs, or screenshots. |
| 72 | + |
| 73 | +## Deploy |
| 74 | + |
| 75 | +1. Create a private fork or private copy for the account-specific deployment. |
| 76 | +2. Review `.github/workflows/main.yml` before adding credentials. |
| 77 | +3. Add `API_ID`, `API_HASH`, and `SESSION_STRING` as Actions secrets. |
| 78 | +4. Add `BOT_CONFIG` as an Actions variable. |
| 79 | +5. Confirm the workflow's `GITHUB_TOKEN` may write repository contents so it can |
| 80 | + update the `logs` branch. |
| 81 | +6. Enable Actions and run **Telegram Auto Sign** manually. |
| 82 | +7. Verify the target bot conversations from Telegram. |
| 83 | + |
| 84 | +The public source repository contains no account configuration. Keeping the |
| 85 | +deployment private reduces accidental disclosure through logs and future |
| 86 | +configuration changes. |
| 87 | + |
| 88 | +## Schedule and logs |
| 89 | + |
| 90 | +Edit the cron expression in `.github/workflows/main.yml` to change the schedule. |
| 91 | +GitHub Actions cron uses UTC and scheduled jobs may start late. |
| 92 | + |
| 93 | +Run records are stored in `checkin.log` on the `logs` branch. They list target |
| 94 | +usernames and commands but do not prove that a destination bot accepted or |
| 95 | +processed a command. |
| 96 | + |
| 97 | +## Local validation |
| 98 | + |
| 99 | +Check Python syntax without connecting to Telegram: |
| 100 | + |
| 101 | +```bash |
| 102 | +python -m py_compile main.py |
| 103 | +``` |
| 104 | + |
| 105 | +Running `main.py` requires real credentials and sends real messages. Use a |
| 106 | +disposable account and test bot when integration testing is necessary. |
| 107 | + |
| 108 | +## Security |
| 109 | + |
| 110 | +- Treat `SESSION_STRING` as a full account credential. |
| 111 | +- Use a dedicated Telegram account with minimal access where practical. |
| 112 | +- Review every workflow change before approving it in a credentialed fork. |
| 113 | +- Keep Actions logs and artifacts free of session values and private chats. |
| 114 | +- Revoke active Telegram sessions immediately after suspected exposure. |
| 115 | +- Do not accept pull requests that print environment variables or session data. |
| 116 | + |
| 117 | +Follow [SECURITY.md](SECURITY.md) for vulnerability reports. |
| 118 | + |
| 119 | +## Contributing and support |
| 120 | + |
| 121 | +Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a change. See |
| 122 | +[SUPPORT.md](SUPPORT.md) for usage questions and bug reports. Participation is |
| 123 | +governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). |
| 124 | + |
| 125 | +## License |
| 126 | + |
| 127 | +TelegramAutoSignBot is available under the [MIT License](LICENSE). |
0 commit comments