git:20260425.5f4618b to git:20260713.4138e1a

31 added, 26 removed. Audit B to B.

---

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: "pairing"`, empty allowlist). Show:

- - DM policy and what it means in one line

+ = 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, policy is pairing, nobody allowed → *"DM your bot on

- Telegram. It replies with a code; approve with `/telegram:access pair

- <code>`."*

+ - 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."*

- **Push toward lockdown — always.** The goal for every setup is `allowlist`

- with a defined list. `pairing` is not a policy to stay on; it's a temporary

- way to capture Telegram user IDs you don't know. Once the IDs are in, pairing

- has done its job and should be turned off.

+ **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 yes and policy is still `pairing`** → *"Good. Let's lock it down so

- nobody else can trigger pairing codes:"* and offer to run

- `/telegram:access policy allowlist`. Do this proactively — don't wait to

- be asked.

- 4. **If no, people are missing** → *"Have them DM the bot; you'll approve

- each with `/telegram:access pair <code>`. Run this skill again once

- everyone's in and we'll lock it."*

- 5. **If the allowlist is empty and they haven't paired themselves yet** →

- *"DM your bot to capture your own ID first. Then we'll add anyone else

- and lock it down."*

- 6. **If policy is already `allowlist`** → confirm this is the locked state.

- If they need to add someone: *"They'll need to give you their numeric ID

- (have them message @userinfobot), or you can briefly flip to pairing:

- `/telegram:access policy pairing` → they DM → you pair → flip back."*

- Never frame `pairing` as the correct long-term choice. Don't skip the lockdown

- offer.

+ 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>`).