Telegram Reader

# telegram-reader

Read-only Telegram skill for financial news and market research using [tdl](https://github.com/iyear/tdl).

## What it does

Reads Telegram channels and groups for financial news — exporting messages, listing channels, and monitoring financial news feeds. Capabilities include:

- **List chats** — view all your Telegram channels, groups, and contacts with filtering
- **Export messages** — read recent messages from any channel or group you've joined
- **Time-range queries** — fetch messages from specific time periods
- **Channel search** — find channels by name or type

**This skill is read-only.** It does NOT support sending messages, joining/leaving channels, or any write operations.

## Authentication

Requires a one-time interactive login via QR code or phone number. After login, the session persists on disk — no further authentication needed.

## Triggers

- "check my Telegram", "read Telegram channel", "Telegram news"
- "what's new in my Telegram channels", "export messages from"
- "financial news on Telegram", "crypto Telegram", "market news Telegram"
- Any mention of Telegram in context of financial news or market research

## Platform

Works on **Claude Code** and other CLI-based agents. Does **not** work on Claude.ai — the sandbox restricts network access and binaries required by tdl.

## Setup

```bash
# As a plugin (recommended — installs all skills)
npx plugins add himself65/finance-skills --plugin finance-social-readers

# Or install just this skill
npx skills add himself65/finance-skills --skill telegram-reader
```

See the [main README](../../../../README.md) for more installation options.

## Prerequisites

- [tdl](https://github.com/iyear/tdl) installed (`brew install telegram-downloader` on macOS)
- One-time login: `tdl login -T qr` (scan QR code with Telegram mobile app)

## Reference files

- `references/commands.md` — Complete tdl command reference for reading channels and exporting messages


# tdl Command Reference (Read-Only)

Complete reference for tdl commands used in the telegram skill. Only read operations are documented — this skill does not support write operations.

## Global Flags

| Flag | Description |
|------|-------------|
| `-n NAMESPACE` | Use a specific namespace (default: `default`) |
| `--proxy PROXY` | Set proxy (e.g., `socks5://127.0.0.1:1080`, `http://127.0.0.1:7890`) |

## Login

### QR Code Login (recommended)

```bash
tdl login -T qr
```

Displays a QR code in the terminal. Scan with Telegram mobile app (Settings > Devices > Link Desktop Device).

### Phone + Code Login

```bash
tdl login -T code
```

Enter phone number and verification code interactively.

### Desktop Client Import

```bash
tdl login
```

Imports session from Telegram Desktop. Client must be from [official website](https://desktop.telegram.org/), not App Store or Microsoft Store.

Optional flags:

| Flag | Description |
|------|-------------|
| `-T TYPE` | Login type: `qr`, `code`, or desktop import (default) |
| `-n NAMESPACE` | Login to a specific namespace |
| `-p PASSCODE` | Passcode for desktop client (if set) |
| `-d PATH` | Custom path to desktop client data |

## List Chats

```bash
tdl chat ls [flags]
```

| Flag | Description |
|------|-------------|
| `-o json` | Output as JSON |
| `-f "FILTER"` | Filter expression |

### Filter examples

```bash
# All channels
tdl chat ls -f "Type contains 'channel'"

# Search by name
tdl chat ls -f "VisibleName contains 'Bloomberg'"

# Channels with specific name
tdl chat ls -f "Type contains 'channel' && VisibleName contains 'Finance'"

# Groups with topics
tdl chat ls -f "len(Topics)>0"

# List available filter fields
tdl chat ls -f -
```

## Export Messages

```bash
tdl chat export -c CHAT [flags]
```

### Chat identifier formats

| Format | Example |
|--------|---------|
| Username (with @) | `-c @channel_name` |
| Username (without @) | `-c channel_name` |
| Numeric chat ID | `-c 123456789` |
| Public link | `-c https://t.me/channel_name` |
| P