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

telegram-init skill

safe

/plugins/telegram-connector/skills/telegram-init

This skill initializes Telegram connection, validates credentials, lists groups, and configures a default channel for seamless messaging sync.

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

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

Files (2)

SKILL.md

2.0 KB

---
name: telegram-init
description: "Initialize Telegram configuration. Use when user wants to set up, configure, or connect their Telegram account for the first time."
---

# telegram-init

Initialize Telegram connection and configure sync settings.

## Trigger Phrases

- "set up Telegram"
- "configure Telegram"
- "initialize Telegram"
- "connect Telegram"
- "telegram init"

## Description

This skill initializes your Telegram connection by:
1. Validating your Telegram API credentials
2. Testing the session string authentication
3. Listing all accessible groups and channels
4. Optionally setting a default group for other commands

## Prerequisites

Before using this skill, you must:

1. **Get API credentials** from https://my.telegram.org/apps
   - Log in with your phone number
   - Create an application
   - Note your `API_ID` and `API_HASH`

2. **Generate a session string** using:
   ```bash
   python ${CLAUDE_PLUGIN_ROOT}/scripts/generate_session.py
   ```
   This will prompt for your phone number and verification code.

3. **Add credentials to .env**:
   ```
   TELEGRAM_API_ID=your_api_id
   TELEGRAM_API_HASH=your_api_hash
   TELEGRAM_SESSION=your_session_string
   ```

## Usage

Basic initialization:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_init.py
```

Set a specific group as default:
```bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_init.py --group 1234567890
```

## Output

- Lists all accessible groups with ID, type, and member count
- Updates `config/agents.yaml` with Telegram settings
- Displays next steps for syncing messages

## Warning

Using a user token may violate Telegram's Terms of Service. This tool is intended for personal use only:
- Archiving your own conversations
- Analyzing communities you actively participate in

Use at your own risk.

## Exit Codes

- `0` - Success
- `1` - Authentication error (invalid/expired session)
- `2` - Configuration error (missing credentials)

## Related Skills

- `telegram-list` - List groups and topics
- `telegram-sync` - Sync messages to local storage
- `telegram-read` - Read synced messages

Overview

This skill initializes and configures a Telegram connection so your agent can access and sync Telegram groups and channels. It validates API credentials and session authentication, lists accessible chats, and can set a default target group for subsequent operations. Use it as the first step before syncing or reading Telegram messages.

How this skill works

The tool verifies TELEGRAM_API_ID, TELEGRAM_API_HASH, and a generated session string, then attempts an authenticated session with Telegram. It enumerates all accessible groups and channels, returns IDs, types, and member counts, and writes Telegram settings into the agent configuration file. Optionally it sets a default group ID so other commands know which group to operate on.

When to use it

Setting up Telegram access for the first time
Revalidating credentials after login changes or session expiry
Choosing a default group for message sync or reads
Preparing the agent to sync or analyze Telegram conversations
Troubleshooting authentication or configuration errors

Best practices

Generate the session string on a trusted machine and never share it publicly
Store API_ID, API_HASH, and SESSION in environment variables or a secure .env file
Run the init tool interactively to confirm the correct group or channel before saving defaults
Use a personal account only for archiving or analyzing conversations you participate in
Check exit codes and logs when the tool reports authentication or configuration issues

Example use cases

Initial setup: validate credentials and create Telegram entries in agents configuration
Switch default group: point subsequent sync commands at a specific Telegram group
Audit access: list all groups and channels the current session can reach and confirm member counts
Recover from auth errors: regenerate session, run init, and confirm status before syncing
Onboard a new machine: generate session string, add credentials to .env, and run init to reconfigure access

FAQ

What do I need before running the init tool?

You need API_ID and API_HASH from my.telegram.org and a generated session string from the session generator script. Add these to environment variables or your .env file.

What do the exit codes mean?

Exit 0 means success. Exit 1 indicates authentication failure (invalid or expired session). Exit 2 signals missing or invalid configuration (credentials not provided).