# Telegram Bot Reference — Dual FX Macro Model

Bot name: **EUR/JPY/USD Macro Model**
Admin chat ID: `1031071259` (Bennett)
Recipients file: `data/logs/telegram_recipients.json`

---

## Commands

### Anyone

| Command | What it does |
|---------|--------------|
| `/start` or `/help` | Shows available commands (different options for admin vs regular users) |
| `/whoami` | Shows your chat ID and name |
| `/requestaccess` | Requests access from the admin — admin gets notified with a one-click approval |
| `/leave` | Removes yourself from the alert list (non-admins only) |

### Admin only

| Command | What it does |
|---------|--------------|
| `/list` | Shows all current recipients with names and when they were added |
| `/pending` | Shows pending access requests waiting for approval |
| `/add <chat_id> [name]` | Adds a new recipient — they automatically get a "You're in!" message |
| `/remove <chat_id>` | Revokes access — they automatically get a "You've been removed" message |

Examples:
```
/add 987654321 John
/remove 987654321
```

If someone who isn't admin tries an admin command, they get: *"🚫 That command is admin-only. Use /requestaccess to request access."*

---

## Adding a new person — step by step

1. They find the bot on Telegram and press `/start`
2. Bot tells them: *"You are NOT currently authorised to receive alerts. Use /requestaccess to ask the owner."*
3. They run `/requestaccess`
4. You (admin) get this message:
   ```
   📥 ACCESS REQUEST
   ────────────────
   From: John
   Chat ID: 987654321
   ────────────────
   To approve: /add 987654321 John
   To ignore: do nothing
   ```
5. Tap/copy that `/add` command and send it
6. Bot adds them to the recipients file and sends them: *"🎉 You're in! You'll start receiving alerts on the next signal check."*
7. They receive every alert from then on

---

## Removing a person

Two ways this can happen:

1. **You revoke** — send `/remove 987654321`. Bot removes them and tells them: *"👋 You've been removed from the macro model alerts. Use /requestaccess if you'd like to rejoin."*
2. **They leave voluntarily** — they send `/leave`. Bot removes them and notifies you: *"ℹ️ John (987654321) left the alert list."*

---

## Protections built in

- All management commands (`/add`, `/remove`, `/list`, `/pending`) silently reject anyone who isn't your admin chat ID
- Admin cannot remove themselves by mistake (`/remove` on admin ID is blocked)
- Even if someone else obtains the bot token, they cannot add themselves because only the admin chat ID can run `/add`
- Access requests require admin approval — no auto-approval
- Recipients file is atomic-write to avoid corruption during saves

---

## Alerts the bot sends

| Alert | When it fires | Priority |
|-------|---------------|----------|
| 🚀 Monitor started | On boot | Informational |
| 📊 Daily summary | 06:05 UTC | Informational |
| 🌅 Morning briefing | 07:00 UTC (London open) | Informational |
| 📥 Access request | Someone runs `/requestaccess` | Admin-only |
| ⏰ Event in ~30 min | 25-35 min before score ≥ 80 events (FOMC, ECB, NFP, CPI, BoJ) | Actionable |
| 🎯 Signal detected | Z-score crosses threshold and session is open | Actionable |
| 🔔 Armed signal | Fast polling started for entry | Informational |
| 📈 Order placed | Trade executed with TP/SL | Actionable |
| 🏁 Position closed | TP, SL, hold limit, or z-exit | Actionable |
| 📅 Week ahead outlook | Mondays — summary of the week's key events | Informational |
| ⚠️ State restored after reboot | Monitor restarted with an open position | Actionable |
| 🔄 Trade history reconciled | Startup back-filled missing trades from MT5 | Informational |
| 🔴 Orphaned position | State file says open but MT5 has no matching position (genuine mismatch only) | Actionable |
| ⚠️ Watchdog alert | State file stale, rate data old, MT5 disconnected, etc. | Actionable |

---

## Getting a chat ID (for giving to others)

Easiest way: message `@userinfobot` on Telegram. It replies instantly with your chat ID (a 9-10 digit number).

---

## If something goes wrong

### Bot not responding to commands
- Check monitor is running on VPS — should see `Telegram commands: polled every 30s` in the startup log
- Commands are polled every 30 seconds — there can be up to 30s delay before a command is processed

### Adding someone didn't work
- Confirm their chat ID is correct (they should run `/whoami` and send you the exact number)
- Check the chat ID is all digits (no letters, no `@username`)
- Verify they pressed `/start` on the bot first — Telegram doesn't allow bots to message users who haven't initiated contact

### Recipient added but still not receiving messages
- Make sure they pressed `/start` on the bot before you added them — otherwise Telegram blocks the first message
- Check `data/logs/telegram_recipients.json` — should contain their chat_id entry

### Admin chat ID needs changing
- Edit `TELEGRAM_CHAT_ID` env variable or line 116 in `live_signal_monitor_v2.py`
- Restart the monitor

---

## Recipients file format

`data/logs/telegram_recipients.json` structure:

```json
{
  "recipients": [
    {
      "chat_id": "987654321",
      "name": "John",
      "added_at": "2026-04-18T10:30:00",
      "added_by": "1031071259"
    }
  ],
  "updated_at": "2026-04-18T10:30:00"
}
```

The admin chat ID is always active (from env var) and doesn't need to appear in this file — it's the "owner" who manages everything.

---

## Bot token security

- Never share the bot token with anyone — anyone with it can impersonate the bot
- Token is in `live_signal_monitor_v2.py` line 112 (and in your env var if set)
- If compromised: create a new bot via @BotFather, replace the token, restart monitor

---

*Last updated: April 17, 2026*
*Monitor version: v3.5 — live_signal_monitor_v2.py*