tg-proxy/skill/skill.md

name	description
telegram-reader	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

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

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

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

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)

{
  "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:

# 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)