Do I need to sync Telegram messages before reading?

Yes, you must sync messages first using the telegram_sync tool.

How can I filter results by date?

Use --date with a YYYY-MM-DD value to limit messages to that date.

What formats are available for output?

Default is Markdown; use --json to get a structured JSON output.

telegram-read

npx machina-cli add skill lycfyi/community-agent-plugin/telegram-read --openclaw

Files (1)

SKILL.md

2.9 KB

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:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py

Read from specific group:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --group 1234567890

Show last N messages:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --last 20

Search for keyword:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --search "meeting"

Filter by date:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --date 2026-01-06

Read specific topic:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --group 1234567890 --topic announcements

Output as JSON:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --json

Output Format

Markdown Output (default)

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

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

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

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

Prerequisites

You must sync messages before reading:

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

Source

git clone https://github.com/lycfyi/community-agent-plugin/blob/main/plugins/telegram-connector/skills/telegram-read/SKILL.md

View on GitHub

Overview

Reads messages from locally synced Telegram data. It can show recent messages, search keywords, or filter by date and group. Useful for recalling conversations or auditing discussions.

How This Skill Works

The skill queries locally stored Telegram messages via the telegram_read tool. Filter by group, last, search, date, or topic to narrow results, and output can be Markdown by default or JSON with --json.

When to Use It

You need to review a specific Telegram group conversation quickly.
You want to search for a keyword across messages.
You want to see the most recent activity in a group.
You need messages from a specific date for an audit.
You want to export messages for analysis or reporting.

Quick Start

Step 1: Sync messages for the target group: python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890
Step 2: Read messages from the group: python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --group 1234567890
Step 3: Narrow results with a filter: python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --last 20

Best Practices

Sync messages first with telegram_sync.py before reading.
Limit scope with --group and --last to speed results.
Use --search with keywords to target results.
Combine --date with --topic for precise filtering.
Export to JSON (--json) for downstream processing.

Example Use Cases

Recall what was said in a group about a project.
Find all mentions of a keyword across messages in a group.
Verify who participated in a topic by date.
Audit a date-specific discussion for compliance.
Export group messages to JSON for analytics.

Frequently Asked Questions

Add this skill to your agents