telegram-sync

Sync Telegram messages to local Markdown storage.

Trigger Phrases

"sync Telegram"
"pull from Telegram"
"fetch Telegram messages"
"download Telegram history"
"telegram sync"
"sync my Telegram DMs"

Description

This skill downloads messages from Telegram groups and DMs to local Markdown files. Messages are stored in an LLM-friendly format that can be easily read and analyzed.

DMs are synced by default. Use

--no-dms

to sync groups only.

Usage

Basic Sync (Groups + DMs)

Sync all (groups + DMs, last 7 days):

bash

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py

Sync groups only (exclude DMs):

bash

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --no-dms

Sync Specific Group

bash

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

Sync Specific DM

bash

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --dm 123456789

Time Range

Sync last 30 days:

bash

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --days 30

Full sync (ignore previous state):

bash

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --full

Forum Topics

Sync specific topic in a forum group:

bash

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890 --topic 5

Custom Limits

Sync with custom message limit for groups:

bash

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --days 30 --limit 5000

Sync with custom DM limit (default is 100 for privacy):

bash

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --dm-limit 500

Message Limits

Group Limit (

--limit

)

Default: 2000 (configurable in
```
config/agents.yaml
```
)
Use higher limits for longer lookback periods
Example:
```
--days 90 --limit 10000
```
for 90-day archive

DM Limit (

--dm-limit

)

Default: 100 (privacy-conscious default)
Lower than group limit by design
Increase manually if needed:
```
--dm-limit 500
```

Sync Modes

Incremental Sync (default)

Only fetches messages newer than the last sync
Fast and efficient for regular updates
Uses the
```
last_message_id
```
from sync state

Full Sync (--full)

Ignores previous sync state
Downloads all messages within the date range
Use when you want a fresh start

Output

Groups

Group messages are saved to:

data/{group_id}-{slug}/messages.md
data/{group_id}-{slug}/sync_state.yaml
data/{group_id}-{slug}/group.yaml

For forum groups with topics:

data/{group_id}-{slug}/{topic_name}/messages.md

DMs

DM messages are saved to a separate directory:

dms/telegram/{user_id}-{name}/messages.md
dms/telegram/{user_id}-{name}/sync_state.yaml
dms/telegram/{user_id}-{name}/user.yaml
dms/telegram/manifest.yaml

Rate Limiting

Telegram has strict rate limits. The sync tool:

Adds delays between requests (100ms minimum)
Handles FloodWait errors automatically
Shows progress during sync

If rate limited, you'll see the wait time and can retry later.

Message Format

markdown

## 2026-01-06

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

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

[photo: vacation.jpg (1.2MB)]

Reactions: heart 5 | thumbsup 3

Exit Codes

```
0
```
- Success
```
1
```
- Authentication error
```
2
```
- Group not found or permission denied
```
3
```
- Rate limited

Troubleshooting

"Could not find the input entity" Error

Error message:

Could not find the input entity for PeerUser(user_id=...) (PeerUser)

What this means: Telethon (the Telegram library) doesn't have this group cached locally. It needs to know the group's "access hash" which is typically cached when you interact with the group.

Solutions (try in order):

Run telegram-list first to refresh the entity cache:
bash
```
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py
```
This iterates through all your dialogs and caches the entities.

Use the exact ID from telegram-list output:

bash

# First, list groups to get correct IDs
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py

# Then sync using the ID shown
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group <ID_FROM_LIST>

Open the group in Telegram app:
- Open the Telegram desktop or mobile app
- Navigate to the group you want to sync
- Send a message or just open the chat
- This forces Telegram to cache the entity
- Then retry the sync
For supergroups/channels: Make sure you're using the correct ID format. Supergroup IDs are typically positive integers (not negative).

"No group specified" Error

Error message:

No group specified and no default group configured.

Solution: Either specify a group ID or set a default:

bash

# Option 1: Specify group directly
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890

# Option 2: Set a default group
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_init.py --group 1234567890

Permission Denied (Exit Code 2)

Possible causes:

You're not a member of the group
The group is private
You've been banned from the group
Admin permissions are required

Solution: Check your membership status in the Telegram app.

Rate Limited (Exit Code 3)

Error message:

Rate limited: Wait X seconds.

Solution: Wait the specified time before retrying. Telegram rate limits are strict and cannot be bypassed.

Related Skills

```
telegram-init
```
- Initialize Telegram connection
```
telegram-list
```
- List groups and topics
```
telegram-read
```
- Read synced messages

telegram-sync

NPX Install

Tags

SKILL.md Content

telegram-sync

Trigger Phrases

Description

Usage

Basic Sync (Groups + DMs)

Sync Specific Group

Sync Specific DM

Time Range

Forum Topics

Custom Limits

Message Limits

Group Limit (
`--limit`
)

DM Limit (
`--dm-limit`
)

Sync Modes

Incremental Sync (default)

Full Sync (--full)

Output

Groups

DMs

Rate Limiting

Message Format

Exit Codes

Troubleshooting

"Could not find the input entity" Error

"No group specified" Error

Permission Denied (Exit Code 2)

Rate Limited (Exit Code 3)

Related Skills

telegram-sync

NPX Install

Tags

SKILL.md Content

telegram-sync

Trigger Phrases

Description

Usage

Basic Sync (Groups + DMs)

Sync Specific Group

Sync Specific DM

Time Range

Forum Topics

Custom Limits

Message Limits

Group Limit (--limit)

DM Limit (--dm-limit)

Sync Modes

Incremental Sync (default)

Full Sync (--full)

Output

Groups

DMs

Rate Limiting

Message Format

Exit Codes

Troubleshooting

"Could not find the input entity" Error

"No group specified" Error

Permission Denied (Exit Code 2)

Rate Limited (Exit Code 3)

Related Skills

Group Limit (
`--limit`
)

DM Limit (
`--dm-limit`
)