Skip to content

Commit 7a8c709

Browse files
0xtbug0xtbug
committed
docs: add auto re-login (OTP webhook) documentation
Create docs/auto-relogin.md to detail the architecture, setup, and API. Update README.md, cli.md, openwrt.md, systemd.md, and telegram-bot.md to reference the new guide and provide environment variable examples. This provides comprehensive guidance for automatic session renewal, reducing manual intervention for expired sessions.
1 parent 4fd99b5 commit 7a8c709

6 files changed

Lines changed: 172 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Go-based tool for managing Telkomsel accounts via **Telegram Bot**, **Terminal C
99
- 📦 Browse recommended packages
1010
- 🛍️ Purchase packages (Pulsa / QRIS)
1111
- ⏰ Auto-buy monitor (auto-purchase when quota is depleted or below a custom MB threshold)
12+
- 🔄 Auto re-login via OTP webhook (session renewal without manual intervention)
1213
- 🤖 MCP server for AI agent integration
1314

1415
## Quick Start
@@ -67,6 +68,8 @@ To install the binary globally so you can run `telbot` from any folder:
6768
|----------|----------|-------------|
6869
| `TELKOMSEL_BOT_TOKEN` | Bot mode | Telegram bot token from BotFather |
6970
| `TELEGRAM_ADMIN_ID` | Bot mode | Your Telegram user ID |
71+
| `OTP_WEBHOOK_PORT` | Optional | Port for OTP webhook listener (e.g. `8081`) |
72+
| `OTP_WEBHOOK_SECRET` | Optional | Shared secret for webhook authentication |
7073

7174
You can either export these directly in your terminal, or place them in a `.env` file located in your platform's standard configuration directory:
7275

@@ -90,8 +93,10 @@ See the [docs/](docs/) folder for detailed guides:
9093
- [Telegram Bot](docs/telegram-bot.md)
9194
- [CLI Mode](docs/cli.md)
9295
- [MCP Server](docs/mcp-server.md)
96+
- [Auto Re-login (OTP Webhook)](docs/auto-relogin.md)
9397
- [Systemd Service (Linux)](docs/systemd.md)
9498
- [OpenWrt](docs/openwrt.md)
99+
- [SMS Forwarder](sms-forwarder-openwrt/README.md)
95100
- [OpenClaw Skill](telbot-skills/SKILL.md)
96101

97102
## Disclaimer

‎docs/auto-relogin.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Auto Re-login (OTP Webhook)
2+
3+
When a Telkomsel session expires during automation (e.g., auto-buy), Telbot can automatically re-login by receiving the OTP via a webhook from the [SMS Forwarder](../sms-forwarder-openwrt/README.md) running on an OpenWrt device.
4+
5+
## Architecture
6+
7+
```
8+
┌──────────────────────────────────┐
9+
│ OpenWrt (Home) │
10+
│ │
11+
│ Android ──ADB──► sms-forwarder │
12+
│ │ │
13+
│ ┌──────────┴────────┐ │
14+
│ │ 1. Telegram (info)│ │
15+
│ │ 2. POST webhook │ │
16+
│ │ to VPS │ │
17+
│ └──────────┬────────┘ │
18+
└───────────────────────┼──────────┘
19+
│ HTTP POST (internet)
20+
▼
21+
┌──────────────────────────────────┐
22+
│ VPS (Telbot) │
23+
│ │
24+
│ HTTP Server (:8081/api/otp) │
25+
│ │ │
26+
│ ▼ │
27+
│ OTP Listener ──► parse OTP │
28+
│ │ (regex) │
29+
│ ▼ │
30+
│ Auto Re-login │
31+
│ ├─ bot mode (auto-buy resumes) │
32+
│ └─ cli mode (auto login) │
33+
└──────────────────────────────────┘
34+
```
35+
36+
## How It Works
37+
38+
1. **Session expires** — Telbot detects `401 Unauthorized` during API calls (e.g., quota check in auto-buy)
39+
2. **Request OTP** — Telbot automatically calls `RequestOTP()` for the phone number
40+
3. **SMS arrives** — Telkomsel sends OTP via SMS to the phone connected to OpenWrt
41+
4. **SMS Forwarder** — Detects new SMS via ADB, POSTs it to Telbot's webhook
42+
5. **Parse & Submit** — Telbot extracts the OTP code (regex), submits it, and gets new tokens
43+
6. **Resume** — Auto-buy continues with the renewed session
44+
45+
## Setup
46+
47+
### Step 1: Configure Telbot (VPS)
48+
49+
Add these environment variables to your `.env`:
50+
51+
```bash
52+
OTP_WEBHOOK_PORT=8081
53+
OTP_WEBHOOK_SECRET=your-random-secret-here
54+
```
55+
56+
Open the firewall port:
57+
```bash
58+
sudo ufw allow 8081/tcp
59+
```
60+
61+
### Step 2: Configure SMS Forwarder (OpenWrt)
62+
63+
See the [SMS Forwarder README](../sms-forwarder-openwrt/README.md) for full installation. Add the webhook config:
64+
65+
```bash
66+
# In /etc/sms-forwarder/sms-forwarder.conf:
67+
WEBHOOK_URL="http://YOUR_VPS_IP:8081/api/otp"
68+
WEBHOOK_SECRET="your-random-secret-here"
69+
```
70+
71+
> **Important:** `WEBHOOK_SECRET` must match `OTP_WEBHOOK_SECRET` in Telbot.
72+
73+
### Step 3: Test
74+
75+
Health check:
76+
```bash
77+
curl http://YOUR_VPS_IP:8081/health
78+
# Expected: ok
79+
```
80+
81+
Simulate an OTP webhook:
82+
```bash
83+
curl -X POST http://YOUR_VPS_IP:8081/api/otp \
84+
-H "Content-Type: application/json" \
85+
-H "X-Webhook-Secret: your-random-secret-here" \
86+
-d '{"from":"+6281219414870","body":"Kode OTP MyTelkomsel Anda: 654321. Jangan berikan ke siapapun."}'
87+
```
88+
89+
## Webhook API
90+
91+
### `POST /api/otp`
92+
93+
Receives SMS content from the SMS Forwarder.
94+
95+
**Headers:**
96+
| Header | Required | Description |
97+
|--------|----------|-------------|
98+
| `Content-Type` | Yes | `application/json` |
99+
| `X-Webhook-Secret` | If configured | Must match `OTP_WEBHOOK_SECRET` |
100+
101+
**Request body:**
102+
```json
103+
{
104+
"from": "+6281xxxxx",
105+
"body": "Kode OTP MyTelkomsel Anda: 123456. Jangan berikan kepada siapapun."
106+
}
107+
```
108+
109+
**Responses:**
110+
```json
111+
{"status":"dispatched","otp":"123456"} // OTP sent to waiting caller
112+
{"status":"no_waiter","otp":"123456"} // No one waiting for OTP
113+
{"status":"no_otp_found"} // Could not parse OTP from body
114+
```
115+
116+
### `GET /health`
117+
118+
Returns `ok` — useful for uptime monitoring.
119+
120+
## OTP Parsing
121+
122+
The listener uses regex to extract OTP codes from SMS body:
123+
124+
| Priority | Pattern | Example Match |
125+
|----------|---------|---------------|
126+
| 1 | `Kode OTP ... 123456` | Specific Telkomsel pattern |
127+
| 2 | Generic 6-digit | Any standalone 6-digit number |
128+
| 3 | Generic 4-digit | Any standalone 4-digit number |
129+
130+
## Behavior
131+
132+
- **Backward compatible** — Without `OTP_WEBHOOK_PORT`, behavior is unchanged (manual login only)
133+
- **Cooldown** — Minimum 2 minutes between re-login attempts per phone number to avoid rate limiting
134+
- **Timeout** — If no OTP is received within 3 minutes, re-login fails and auto-buy stops
135+
- **Fallback** — If auto re-login fails, user is notified and manual login is required
136+
- **Both modes** — Works in both `--bot` and `--cli` modes

‎docs/cli.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,16 @@ No environment variables required — sessions are loaded from `sessions.json`.
3030
## Session Persistence
3131

3232
Sessions are saved to `sessions.json` automatically. If you've logged in before (via CLI, Bot, or MCP), the CLI will pick up the existing session.
33+
34+
## Auto OTP (Optional)
35+
36+
If `OTP_WEBHOOK_PORT` is set as an environment variable, the CLI will start an OTP webhook listener. During login, instead of manually entering the OTP, it will be automatically received from the [SMS Forwarder](../sms-forwarder-openwrt/README.md) webhook.
37+
38+
```bash
39+
# Export before running CLI:
40+
export OTP_WEBHOOK_PORT=8081
41+
export OTP_WEBHOOK_SECRET=your_secret
42+
telbot --cli
43+
```
44+
45+
See [Auto Re-login docs](auto-relogin.md) for full setup guide.

‎docs/openwrt.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ Here is the content of .env
3232
```bash
3333
TELKOMSEL_BOT_TOKEN=your_bot_token
3434
TELEGRAM_ADMIN_ID=your_admin_id
35+
36+
# Optional: Enable auto re-login via OTP webhook from SMS Forwarder
37+
# OTP_WEBHOOK_PORT=8081
38+
# OTP_WEBHOOK_SECRET=your_secret
3539
```
3640

3741
Then copy .env to /.config/telbot/ directory

‎docs/systemd.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ WorkingDirectory=/home/your_username/telkomsel-bot
4747
Environment="TELKOMSEL_BOT_TOKEN=your_telegram_bot_token"
4848
Environment="TELEGRAM_ADMIN_ID=your_telegram_id"
4949

50+
# Optional: Enable auto re-login via OTP webhook from SMS Forwarder
51+
# Environment="OTP_WEBHOOK_PORT=8081"
52+
# Environment="OTP_WEBHOOK_SECRET=your_secret"
53+
5054
# The command to execute
5155
ExecStart=/usr/local/bin/telbot --bot
5256

‎docs/telegram-bot.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@
88
```
99
TELKOMSEL_BOT_TOKEN=your_token_here
1010
TELEGRAM_ADMIN_ID=your_user_id
11+
12+
# Optional: Enable auto re-login via OTP webhook
13+
OTP_WEBHOOK_PORT=8081
14+
OTP_WEBHOOK_SECRET=your_secret
1115
```
1216

1317
## Run
@@ -34,3 +38,9 @@ telbot --bot --verbose
3438
| `/start` | Show main menu |
3539

3640
All other interactions are through inline keyboard buttons.
41+
42+
## Auto Re-login
43+
44+
If an OTP webhook listener is configured (`OTP_WEBHOOK_PORT`), the bot will automatically re-login when a session expires during auto-buy monitoring. This requires the [SMS Forwarder](../sms-forwarder-openwrt/README.md) to be set up on an OpenWrt device.
45+
46+
See [Auto Re-login docs](auto-relogin.md) for full setup guide.

0 commit comments

Comments
 (0)