playbooks

home / skills / lycfyi / community-agent-plugin / telegram-read

telegram-read skill

/plugins/telegram-connector/skills/telegram-read

This skill helps you read and search synced Telegram messages, enabling quick access to conversations and targeted keyword discovery.

npx playbooks add skill lycfyi/community-agent-plugin --skill telegram-read

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.9 KB
---
name: telegram-read
description: "Read and search synced Telegram messages. Use when user asks about Telegram conversations, wants to see messages, or search for specific content."
---

# telegram-read

Read and search synced Telegram messages.

## Trigger Phrases

- "read Telegram messages"
- "what's in the Telegram group"
- "search Telegram for [keyword]"
- "show Telegram messages"
- "telegram read"

## Description

This skill reads messages from locally synced Telegram data. It can show recent messages, search for keywords, or filter by date.

## Usage

Read all messages from default group:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py
```

Read from specific group:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --group 1234567890
```

Show last N messages:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --last 20
```

Search for keyword:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --search "meeting"
```

Filter by date:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --date 2026-01-06
```

Read specific topic:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --group 1234567890 --topic announcements
```

Output as JSON:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --json
```

## Output Format

### Markdown Output (default)

```markdown
# My Group

Group: My Group (1234567890)
Type: supergroup
Last synced: 2026-01-06T12:00:00Z

---

## 2026-01-06

### 10:30 AM - @alice (123456)
Hello everyone!

### 10:31 AM - @bob (789012)
↳ replying to @alice:
Hey Alice!
```

### JSON Output (--json)

```json
{
  "group_id": 1234567890,
  "topic": "general",
  "message_count": 50,
  "messages": [
    {
      "date": "2026-01-06",
      "time": "10:30 AM",
      "author": "@alice (123456)",
      "content": "Hello everyone!"
    }
  ]
}
```

## Search Mode

When using `--search`, only messages containing the keyword are returned:

```bash
python telegram_read.py --search "Python"
```

Output:
```
Found 3 messages matching 'Python':

### 10:30 AM - @alice (123456)
I love Python programming!

----------------------------------------

### 2:15 PM - @charlie (456789)
Python is great for automation

----------------------------------------
```

## Reading Tips

1. **Start with recent messages**: Use `--last 20` to see the latest activity
2. **Search specific topics**: Combine `--topic` with `--search` for targeted searches
3. **Export for analysis**: Use `--json` to get structured data for further processing

## Prerequisites

You must sync messages before reading:
```bash
python plugins/telegram-agent/tools/telegram_sync.py --group 1234567890
```

## Exit Codes

- `0` - Success
- `1` - No synced data found
- `2` - Configuration error

## Related Skills

- `telegram-sync` - Sync messages from Telegram
- `telegram-list` - List groups and topics
- `telegram-send` - Send messages to Telegram

Overview

This skill reads and searches locally synced Telegram messages so you can inspect conversation history, filter by date or topic, and export results. It returns human-friendly Markdown by default and can output structured JSON for downstream processing. Use it to quickly find messages, review recent activity, or produce a message dump for analysis.

How this skill works

The skill reads message data from a local sync of Telegram groups and topics. You can request the latest N messages, search by keyword, filter by date, or target a specific group/topic. Results are formatted as readable Markdown or as JSON when the JSON output flag is used.

When to use it

  • You want to view recent activity in a Telegram group or topic
  • You need to find messages that contain a specific keyword or phrase
  • You want to export message data for analysis or reporting
  • You need to review messages from a particular date
  • You want a quick summary of synced conversations

Best practices

  • Always run the Telegram sync step before reading to ensure data is up to date
  • Start with --last N to quickly inspect recent activity before broad searches
  • Combine --topic with --search to limit results to a focused discussion thread
  • Use --json when you plan to ingest results into a script or analysis tool
  • Filter by date to narrow large history ranges and speed up queries

Example use cases

  • Show the last 20 messages from the default synced group to catch up on recent discussion
  • Search group history for the keyword "meeting" to find scheduling messages and decisions
  • Export a topic's messages to JSON for sentiment analysis or archival
  • Filter messages from a specific date to reconstruct what was discussed on that day
  • Read announcements in a named topic to collect official updates

FAQ

Do I need to sync messages before using this skill?

Yes. The skill reads from locally synced Telegram data. Run the sync step first to ensure the latest messages are available.

Can I output results as structured data?

Yes. Use the JSON output flag to get a machine-friendly JSON representation of group, topic, and message fields.

How do I search only a specific topic?

Combine the group identifier with the --topic parameter and add --search with your keyword to restrict results to that topic.