---
name: telegram-reader
description: Read-only access to Telegram via tg-proxy API. Use when the user asks about recent messages, wants to search chats, or needs inbox summary.
---

# Telegram Reader

Read-only interface to wzray's Telegram via `https://tg-proxy.wzray.com`.

## Endpoints

Base URL: `https://tg-proxy.wzray.com`

### 1. Get Chats
```bash
curl -s "https://tg-proxy.wzray.com/chats?limit=50&offset=0"
```
Returns: `{"items": [{id, title, type, chat_type, muted, archived, folder_id, folder_ids, pinned, ...}], "limit", "offset", "has_more", "remaining_count"}`

Supported query params:
- `limit`
- `offset`
- `archived=true|false`
- `chat_type=direct|bot|group|channel`
- `folder_id` — filter chats by Telegram folder/dialog filter id (get list from `/folders`)

### 2. Get Folders
```bash
curl -s "https://tg-proxy.wzray.com/folders"
```
Returns: `[{id, title, type, icon_emoji, pinned_chat_ids, include_chat_ids, exclude_chat_ids, contacts, non_contacts, groups, broadcasts, bots, exclude_muted, exclude_read, exclude_archived, has_my_invites}]`

### 3. Get Messages in Chat
```bash
curl -s "https://tg-proxy.wzray.com/chats/{chat_id}/messages?limit=50&offset=0"
```
Returns: `{"chat": {...}, "items": [{id, date, text, from_user, chat_id, from_me, is_outgoing, reply_to_message_id, quoted_text, reply_snippet, edited_at, is_read, attachments}], "limit", "offset", "has_more"}`

### 4. Get Messages Delta
```bash
curl -s "https://tg-proxy.wzray.com/chats/{chat_id}/delta?since=2026-02-16T06:00:00Z&limit=50&offset=0"
```
Returns: `{"chat": {...}, "items": [...], "limit", "offset", "has_more", "remaining_count"}`

Notes:
- `since` is required for `delta`
- `delta` returns messages in chronological order
- `offset` is applied inside the filtered `since` window
- `remaining_count` is present where the server can compute it cheaply and accurately
- `null` fields are omitted from JSON output
- responses are pretty-printed JSON

## State

State stored in: `runtime/telegram-reader/state.json` (gitignored, persists locally)

```json
{
  "last_check": "2026-02-16T10:30:00Z",
  "watched_chats": [-1003680985286, ...],
  "watched_names": {"-1003680985286": "is-tech-y28", ...},
  "last_message_ids": {}
}
```

## JS Client

`skills/scripts/telegram-reader/tg-client.js` — удобный CLI для API:

```bash
# List folders
node skills/scripts/telegram-reader/tg-client.js get-folders

# List chats
node skills/scripts/telegram-reader/tg-client.js get-chats --limit 50

# Only archived groups
node skills/scripts/telegram-reader/tg-client.js get-chats --archived true --chat-type group

# Filter chats by folder
node skills/scripts/telegram-reader/tg-client.js get-chats --folder-id 2

# Filter chats (client-side)
node skills/scripts/telegram-reader/tg-client.js filter-chats --active-last-week --not-muted --type=direct

# Get delta
node skills/scripts/telegram-reader/tg-client.js delta 5880803391 "2026-02-16T00:00:00Z"
```

## Behavior

### On Heartbeat (hourly)
1. Load state
2. For each watched chat, get delta since `last_check`
3. Filter important messages:
   - Mentions (@wzray)
   - Keywords: "важно", "срочно", "deadline", "сегодня"
   - Unread DMs
4. Summarize and notify if significant
5. Update `last_check` to now

### When User Asks
- "Что нового?" → run delta since last_check, summarize
- "Что писал [кто-то]?" → search in recent messages
- "Покажи чаты" → list chats from API

## Priority Filters

For heartbeat summaries, prioritize:
1. DMs with unread/unanswered messages
2. Messages mentioning user
3. Messages with urgency keywords
4. Pinned/important chats

Ignore:
- Channels (unless user explicitly watches them)
- Muted chats
- Large groups with high traffic (unless mentioned)