configure

name	configure
description	Set up the Telegram channel — save the bot token and review access policy. Use when the user pastes a Telegram bot token, asks to configure Telegram, asks "how do I set this up" or "who can reach me," or wants to check channel status.
user-invocable	true
allowed-tools	["Read","Write","Bash(ls *)","Bash(mkdir *)"]

/telegram:configure — Telegram Channel Setup

Writes the bot token to {STATE_DIR}/.env and orients the user on access policy. The server reads both files at boot.

Arguments passed: $ARGUMENTS

---

State directory resolution

Compute STATE_DIR at the very start before doing anything else:

1. If $TELEGRAM_STATE_DIR env var is set:
     STATE_DIR = $TELEGRAM_STATE_DIR

2. Else if {CWD}/.telegram-state/ exists:
     STATE_DIR = {CWD}/.telegram-state
   (This handles gateway agent sessions where CWD = workspace dir)

3. Else:
     STATE_DIR = ~/.claude/channels/telegram  (legacy fallback)

Use STATE_DIR for all file paths:

• Token file: {STATE_DIR}/.env
• Access file: {STATE_DIR}/access.json

---

Dispatch on arguments

No args — status and guidance

Read both state files and give the user a complete picture:

1. Token — check {STATE_DIR}/.env for TELEGRAM_BOT_TOKEN. Show set/not-set; if set, show first 10 chars masked (123456789:...).

2. Access — read {STATE_DIR}/access.json (missing file = defaults: dmPolicy: "allowlist", pairing: true, empty allowlist). Show:

   • DM policy (open/allowlist/disabled) and what it means in one line
   • Pairing toggle (on/off) and what it means in one line
   • Allowed senders: count, and list display names or IDs
   • Pending pairings: count, with codes and display names if any

3. What next — end with a concrete next step based on state:

   • No token → "Run /telegram:configure <token> with the token from BotFather."
   • Token set, allowlist + pairing on, nobody allowed → "DM your bot on Telegram. It replies with a code — approve it from the web Channels card (or run /telegram:access pair <code> here)."
   • Token set, someone allowed → "Ready. DM your bot to reach the assistant."

The access model. The base policy should be allowlist — only people on the list reach the assistant. Pairing is an orthogonal on/off toggle (default on) that sits on top of allowlist: when on, an unknown sender who DMs the bot gets a one-time code that shows up in Pending, and the admin approves it (from the web Channels card, or /telegram:access pair <code>). It's a lightweight identity check, and it's fine to leave on as your standing way to let new people in. Turn pairing off only if you want a hard allowlist where strangers are dropped silently with no code.

Drive the conversation this way:

1. Read the allowlist. Tell the user who's in it.
2. Ask: "Is that everyone who should reach you through this bot?"
3. If someone's missing → "Leave pairing on: have them DM the bot, then approve the code that appears in Pending (web card or /telegram:access pair <code>)."
4. If the allowlist is empty and they haven't paired themselves yet → "DM your bot to capture your own ID first — approve the code and you're in."
5. If they want a hard lockdown (no new codes for strangers) → offer to run /telegram:access pairing off. This keeps allowlist but stops minting codes; add people later by flipping pairing back on, or with /telegram:access allow <senderId>.

<token> — save it

1. Treat $ARGUMENTS as the token (trim whitespace). BotFather tokens look like 123456789:AAH... — numeric prefix, colon, long string.
2. mkdir -p {STATE_DIR}
3. Read existing .env if present; update/add the TELEGRAM_BOT_TOKEN= line, preserve other keys. Write back, no quotes around the value.
4. chmod 600 {STATE_DIR}/.env — the token is a credential.
5. Confirm, then show the no-args status so the user sees where they stand.

clear — remove the token

Delete the TELEGRAM_BOT_TOKEN= line (or the file if that's the only line).

---

Implementation notes

• The channels dir might not exist if the server hasn't run yet. Missing file = not configured, not an error.
• The server reads .env once at boot. Token changes need a session restart or /reload-plugins. Say so after saving.
• access.json is re-read on every inbound message — policy changes via /telegram:access take effect immediately, no restart.
• Groups need more than allowlisting. DMs work over long-polling, but in a group Telegram's default Privacy Mode stops the bot from receiving plain messages (it only gets /commands, @mentions, and replies), and commands are dropped in groups anyway. To use groups, tell the user to promote the bot to Admin in the group (or disable Privacy Mode in BotFather and re-add it), then allowlist the group via /telegram:access (pairing code or group allow <groupId>).