telegram-assistant

Original source / Raw SKILL.md

---
name: telegram-assistant
description: |
  Telegram automation assistant using telegram-mcp. Use when users want to:
  (1) Get a digest of unread Telegram messages
  (2) Analyze their writing style from channel posts
  (3) Draft and publish posts to Telegram channels
  (4) Search and reply to messages across chats
  Triggers: "telegram digest", "unread messages", "morning summary",
  "post to channel", "draft telegram post", "analyze writing style",
  "extract style from channel", "telegram workflow"
license: MIT
compatibility: |
  Requires telegram-mcp server configured in Claude Code.
  See references/setup.md for installation instructions.
metadata:
  author: Bayram Annakov (onsa.ai)
  version: "1.0.0"
  category: productivity
  telegram-mcp-repo: https://github.com/chigwell/telegram-mcp
allowed-tools: mcp__telegram-mcp__* Read Write Edit Glob
---

# Telegram Assistant

Automate Telegram workflows with AI: digests, channel posting, and style-matched drafts.

## Quick Start

```
Need morning digest?     → Use Digest Workflow
Want to post to channel? → Use Style + Post Workflow
Replying to messages?    → Use Reply Workflow
```

---

## Workflow 1: Digest

**Goal**: Summarize unread messages across all chats.

### Step 1: Get Unread Chats
```
Use list_chats to find chats with unread messages.
Look for "Unread:" in the output (both count and "marked" flag).
```

### Step 2: Read Recent Messages
For each chat with unread:
1. Use `get_messages` or `list_messages` to fetch recent messages
2. Focus on messages since last read

### Step 3: Summarize
Create a digest with:
- **Priority items**: Direct mentions, questions needing response
- **Updates**: News, announcements from channels
- **Low priority**: General chatter, FYI items

### Step 4: Draft Replies (Optional)
For messages needing response:
1. Draft a reply
2. Use `save_draft` to save it for user review
3. User can review and send manually in Telegram app

**Safety**: Never send messages directly. Always save as draft first.

---

## Workflow 2: Style Extraction

**Goal**: Analyze channel posts to capture user's writing style.

### Step 1: Fetch Posts
```
Use list_messages with the channel name/ID.
Fetch last 15-20 posts (skip media-only posts).
```

### Step 2: Analyze Patterns
Extract these characteristics:
- **Language mix**: Ratio of Russian to English terms
- **Structure**: Use of hooks, tldr, bullets, numbered lists, sections
- **Tone**: Formal (вы) vs casual (ты), first-person usage (я/мы)
- **Length**: Average post length in words
- **Emoji**: Frequency and types used
- **Call-to-action**: How posts typically end

### Step 3: Generate Style Guide
Create `references/style-guide.md` with:
```markdown
# [Channel Name] Style Guide

## Language
- Primary: Russian with English tech terms
- Formality: [formal/casual]
- Person: [я/мы usage]

## Structure
- Hook: [question/statement/story]
- Sections: [yes/no, with headers?]
- Lists: [bullets/numbered]
- tldr: [yes/no]

## Formatting
- Average length: ~[X] words
- Emoji: [frequent/occasional/rare]
- Common emojis: [list]

## Endings
- Call-to-action style: [question/invitation/resource link]

## Example Patterns
[Include 2-3 anonymized structure examples]
```

### Step 4: Save for Future Use
The style guide is now available for the Post workflow.

---

## Workflow 3: Post to Channel

**Goal**: Draft a post matching user's writing style.

### Pre-requisite
Run Style Extraction workflow first if `references/style-guide.md` doesn't exist.

### Step 1: Read Style Guide
```
Read references/style-guide.md to understand the target style.
```

### Step 2: Understand Topic
Ask user for:
- Topic/subject matter
- Key points to cover
- Target audience (if different from usual)
- Any specific call-to-action

### Step 3: Draft Post
Write the post following the style guide:
- Match language mix ratio
- Use the same structural patterns
- Maintain consistent tone
- Include appropriate emoji (if style uses them)
- End with typical call-to-action pattern

### Step 4: User Review
Present the draft to user for feedback. Iterate if needed.

### Step 5: Save as Draft
```
Use save_draft(chat_id="ChannelName", message="draft content")
```

User can then:
1. Open Telegram app
2. Go to the channel
3. See the draft in the input field
4. Review and send when ready

**Safety**: Always use `save_draft`, never `send_message` for channel posts.

---

## Workflow 4: Search & Reply

**Goal**: Find specific messages and draft contextual replies.

### Step 1: Search
```
Use search_messages(chat_id, query) to find relevant messages.
Or list recent messages and filter manually.
```

### Step 2: Get Context
```
Use get_message_context(chat_id, message_id) to see surrounding messages.
```

### Step 3: Draft Reply
Write a contextual reply based on the conversation flow.

### Step 4: Save as Draft Reply
```
Use save_draft(chat_id, message, reply_to_msg_id=message_id)
```

User reviews and sends from Telegram app.

---

## Safety Guidelines

1. **Draft First**: Never use `send_message` for important communications. Always `save_draft`.

2. **Verify Chat ID**: Double-check you're targeting the right chat before any action.

3. **Rate Limits**: Avoid rapid-fire API calls. Space out requests if processing many chats.

4. **Privacy**: The AI sees all accessible chats. Be mindful of sensitive conversations.

5. **Session Security**: The session string provides full account access. Treat it like a password.
   - On macOS: Store in Keychain (see setup.md) rather than .env files
   - Never commit credentials to git

---

## Troubleshooting

### "Could not find the input entity"
- Use channel username (without @) or numeric ID
- For supergroups, try prepending -100 to the ID

### "Chat not found"
- Ensure the account has access to the chat
- Try using the exact chat title from `list_chats`

### Draft not appearing
- Open the specific chat in Telegram app
- Drafts are saved per-chat

---

## Resources

- **telegram-mcp repo**: https://github.com/chigwell/telegram-mcp
- **Setup guide**: [references/setup.md](references/setup.md)
- **Style guide template**: [references/style-guide.md](references/style-guide.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/setup.md

```markdown
# Telegram MCP Setup Guide

This guide walks through setting up the telegram-mcp server for use with Claude Code.

## Prerequisites

- Python 3.10+
- uv (Python package manager)
- Telegram account
- Telegram API credentials (get from https://my.telegram.org)

## Step 1: Get Telegram API Credentials

1. Go to https://my.telegram.org
2. Log in with your phone number
3. Click "API development tools"
4. Create a new application (any name/platform)
5. Note your `api_id` and `api_hash`

## Step 2: Clone and Install

```bash
# Clone the repository
git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp

# Install dependencies
uv sync
```

## Step 3: Create Environment File

Create a `.env` file in the telegram-mcp directory:

```bash
# Telegram API Credentials
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash

# Session Management
TELEGRAM_SESSION_NAME=claude_session
```

## Step 4: Generate Session String

This step requires manual interaction (entering phone number and code):

```bash
uv run python session_string_generator.py
```

Follow the prompts:
1. Enter your phone number (with country code, e.g., +1234567890)
2. Enter the verification code sent to your Telegram
3. Enter 2FA password if enabled

The script will output a session string. Add it to your `.env`:

```bash
TELEGRAM_SESSION_STRING=your_generated_session_string
```

## Step 5: Add to Claude Code

```bash
# Add the MCP server to Claude Code
claude mcp add telegram-mcp -s user -- uv run --directory /path/to/telegram-mcp python main.py

# Verify it was added
claude mcp list
```

Replace `/path/to/telegram-mcp` with the actual path to your cloned repository.

## Step 6: Restart Claude Code

Close and reopen Claude Code for the MCP server to be available.

## Verification

Test the setup by asking Claude Code to list your Telegram chats:

```
"Show me my recent Telegram chats"
```

If working correctly, you should see a list of your chats.

---

## Troubleshooting

### "Could not find the input entity for PeerUser"

**Cause**: The chat ID format is incorrect.

**Fix**:
- For users: Use the numeric ID directly
- For groups: Use the group name or ID
- For supergroups/channels: Prepend `-100` to the ID (e.g., `-1001234567890`)

### "Session expired" or authentication errors

**Cause**: The session string may be invalid or expired.

**Fix**: Regenerate the session string:
```bash
uv run python session_string_generator.py
```

### MCP server not appearing in Claude Code

**Cause**: Server not properly registered or path is incorrect.

**Fix**:
1. Check the server list: `claude mcp list`
2. Remove and re-add if needed: `claude mcp remove telegram-mcp`
3. Ensure the path to main.py is absolute

### Rate limiting / FloodWait errors

**Cause**: Too many API requests in a short time.

**Fix**: Wait the specified time (shown in error) before retrying. Space out requests.

### Draft not appearing in Telegram

**Cause**: Drafts are per-chat and may need app refresh.

**Fix**:
1. Open the specific chat in Telegram app
2. The draft should appear in the input field
3. Try closing and reopening the chat

---

## Security Notes

1. **Session String = Full Access**: Treat your session string like a password. Anyone with it can access your Telegram account.

2. **Keep .env Private**: Never commit `.env` to version control.

3. **Review Before Sending**: Always use `save_draft` for important messages. Review in Telegram before sending.

4. **Monitor Activity**: Telegram shows active sessions in Settings > Privacy > Active Sessions.

---

## Resources

- **telegram-mcp repo**: https://github.com/chigwell/telegram-mcp
- **Telethon docs**: https://docs.telethon.dev
- **Telegram API docs**: https://core.telegram.org/api

```