docs: update docs for Telegram integration

docs/API.md

@@ -288,6 +288,75 @@ Same stable attributes and methods as `Bot`:
 
 ---
 
+## `derp.telegram` -- Telegram Adapter
+
+Alternative bot adapter for Telegram via long-polling (`getUpdates`).
+All HTTP routed through SOCKS5 proxy. Exposes the same plugin API as
+`derp.bot.Bot` so protocol-agnostic plugins work without modification.
+
+### `TelegramMessage` dataclass
+
+Duck-typed compatible with IRC `Message`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `raw` | `dict` | Original Telegram Update |
+| `nick` | `str \| None` | Sender first_name (or username fallback) |
+| `prefix` | `str \| None` | Sender user_id as string (for ACL) |
+| `text` | `str \| None` | Message body (stripped of @bot suffix) |
+| `target` | `str \| None` | chat_id as string |
+| `is_channel` | `bool` | `True` for groups, `False` for DMs |
+| `command` | `str` | Always `"PRIVMSG"` (compat shim) |
+| `params` | `list[str]` | `[target, text]` |
+| `tags` | `dict[str, str]` | Empty dict (no IRCv3 tags) |
+
+### `TelegramBot`
+
+Same stable attributes and methods as `Bot`:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | `str` | Always `"telegram"` |
+| `config` | `dict` | Merged TOML configuration |
+| `nick` | `str` | Bot display name (from `getMe`) |
+| `prefix` | `str` | Command prefix (from `[telegram]` or `[bot]`) |
+| `state` | `StateStore` | Persistent key-value storage |
+| `registry` | `PluginRegistry` | Shared command and event registry |
+
+**Sending messages** -- same signatures, Telegram API transport:
+
+| Method | Behaviour |
+|--------|-----------|
+| `send(target, text)` | `sendMessage` API call (proxied, rate-limited) |
+| `reply(msg, text)` | `send(msg.target, text)` |
+| `long_reply(msg, lines, *, label="")` | Paste overflow, same logic as IRC |
+| `action(target, text)` | Italic Markdown text via `sendMessage` |
+| `shorten_url(url)` | Same FlaskPaste integration |
+
+**Message splitting**: messages > 4096 chars split at line boundaries.
+
+**IRC no-ops** (debug log, no error):
+
+`join`, `part`, `kick`, `mode`, `set_topic`
+
+**Plugin management** -- delegates to shared registry:
+
+`load_plugins`, `load_plugin`, `reload_plugin`, `unload_plugin`
+
+**Permission tiers** -- same model, exact user_id string matching:
+
+`_get_tier(msg)`, `_is_admin(msg)`
+
+### Helper Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `_strip_bot_suffix` | `(text: str, bot_username: str) -> str` | Strip `@username` from command text |
+| `_build_telegram_message` | `(update: dict, bot_username: str) -> TelegramMessage \| None` | Parse Telegram Update into message |
+| `_split_message` | `(text: str, max_len: int = 4096) -> list[str]` | Split long text at line boundaries |
+
+---
+
 ## Handler Signatures
 
 All command and event handlers are async functions receiving `bot` and