hive.telegram-notifications-setup

# Telegram Notifications Setup (Sentinel)

Sentinel pings the user on Telegram when a colony stalls and lets them reply to
keep it going. It needs one thing: a **Telegram bot token** (`123456:ABC-…`),
created via @BotFather and stored under credential id `telegram`. The same token
sends alerts and reads the user's replies.

You do the whole thing end to end with the **`sentinel_setup`** tool (the same API
the desktop connector uses): create the bot, store the token, detect the chat,
point Sentinel at it, and send a test — without making the user paste anything.

**Activate `hive.browser-automation` first** — this skill assumes you know the
lifecycle rules (the bridge attaches to the user's own Chrome; never launch or kill
a browser), the screenshot + viewport-fraction coordinate workflow, and
`hive-browser interact`. Telegram Web is a heavy SPA with custom rendering, so prefer the
screenshot + coordinate path over selectors when the snapshot is unclear.

### Telegram Web specifics (verified)

- Telegram Web defaults to the **K version** at `https://web.telegram.org/k/`. The
  selectors below are verified there; fall back to screenshot + coordinates if a
  selector doesn't match (e.g. the older `/a/` version).
- **Message composer:** `#editable-message-text` — click it, `type` your text, send
  with the Enter key. Used for `/newbot`, `/start`, etc.
- **Global search:** the search box is top-left (around `[0.13, 0.04]`). Click it,
  type a name, then click the result row to open that chat.
- **Read a bot's reply as text** (don't OCR a screenshot): run `hive-browser page
  text ".chat-message:last-child" --json` in the terminal — it returns the latest message verbatim — this is
  how you capture the token without transposing characters.

## Before you start — check what already exists

1. Run `sentinel_setup({"action": "status"})`. If it shows `telegram` already
   configured, the token's stored — skip to **Step 3 (detect the chat)** (or
   straight to **Step 4** if the colony config is already set), don't make a new
   bot.
2. Confirm the user is signed into Telegram: run `hive-browser open` /
   `hive-browser navigate https://web.telegram.org/k/ --json` in the terminal. **You cannot log in for them**
   — you don't have their phone or SMS code. If it shows a QR / phone-number login,
   STOP and ask the user to log into Telegram Web in their Chrome, then continue.
   Don't fight the login screen or try to switch login methods yourself.

## Step 1 — Create the bot with @BotFather

@BotFather is Telegram's official bot for managing bots.

1. **Use in-app search to reach BotFather — not `t.me/` URLs.** `t.me/BotFather`
   (and `hive-browser open`-ing it) tends to land on the t.me web page or redirect
   without opening the chat. Instead: click the global search box (top-left), type
   `BotFather`, and click the **verified** result (blue check) to open the chat.
2. In the BotFather chat, click the composer (`#editable-message-text`) and send
   `/newbot`. It asks for:
   - a **display name** (e.g. `Hive Sentinel`), then
   - a **username** that must end in `bot` (e.g. `hive_sentinel_<something>_bot`).
     If the name is taken, BotFather says so — pick another until it's accepted.
3. On success BotFather replies with **"Use this token to access the HTTP API:"**
   followed by the token `123456789:AAE…`. **Read it by running
   `hive-browser page text ".chat-message:last-child" --json` in the terminal, not off a screenshot** — the
   token is long and a single transposed character makes `store_token` fail. Copy
   the exact `digits:rest` string.

## Step 2 — Store the token

```
sentinel_setup({"action": "store_token", "provider": "telegram", "token": "123456789:AAE…"})
```

This validates the token via `getMe` before storing and reports the bot's
`@username`. If it's rejected, re-read the token from BotFather's message and retry
— never invent or pad a token.

> Prefer not to handle the token yourself? Fall back to
> `credentials(action="collect", …)` with `credential_id` `telegram` (field
> `access_token`) to pop a secure form. The default flow above is hands-off and is
> what the in-app "Set this up with the agent" button expects.

## Step 3 — Detect the chat to notify

Telegram bots can only message a user/group **after** that chat has messaged the
bot first. So trigger one message, then detect it:

1. Open the new bot's chat: **search its `@username`** (top-left search) and open
   the result — same as finding BotFather. (Clicking the `t.me/<bot>` link in
   BotFather's reply is less reliable; search is the sure path.)
2. Send `/start` (or any message): a fresh bot chat shows a **Start** button —
   click it; otherwise click the composer (`#editable-message-text`), type
   `/start`, and press Enter. Give it ~2–3s, then detect. That delivers the bot's
   first update.
   - **Group target instead?** Add the bot to the group, then send any message in
     that group. (You may need to disable BotFather's privacy mode via
     `/setprivacy → Disable` so the bot can read group messages.)
3. Run:

```
sentinel_setup({"action": "detect_chat"})
```

It returns the `chat_id` and the `sender_id`. Use the returned `sender_id` for the
allowlist so only that user can drive the colony.

`detect_chat` is **listener-aware**: if this bot is already wired to another colony,
Sentinel's background listener is long-polling Telegram and consuming updates — so a
raw `getUpdates` would always come back empty. The tool handles that for you (it
reads the chat the listener saw), so just call `detect_chat`. If it says **PENDING**,
the message simply hasn't landed yet — make sure Start/your message actually sent,
then retry. **Do not** start decrypting credentials or polling the Telegram API by
hand to debug a PENDING — that fights the listener and gets you nowhere; messaging
the bot and retrying is the whole fix.

## Step 4 — Turn Sentinel on and verify

`configure`/`test` target the colony bound to your session (pas