How do I list topics in a group?

Use --group GROUP_ID to view available topics within that group.

How can I get JSON output?

Run the command with --json to receive a machine-readable JSON array.

What do the exit codes mean?

0 = success, 1 = authentication error, 2 = group not found or configuration error.

telegram-list

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

Files (1)

SKILL.md

2.5 KB

telegram-list

List Telegram groups, channels, DMs, and forum topics.

Trigger Phrases

"list Telegram groups"
"what groups do I have on Telegram"
"show my Telegram channels"
"telegram list"
"list topics in [group]"
"list my Telegram DMs"

Description

This skill lists all accessible Telegram groups, channels, and DMs. DMs are included by default. For groups with forum topics enabled, you can also list the individual topics.

Usage

List all groups and DMs (default):

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py

List groups only (exclude DMs):

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

List topics in a specific group:

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

Output as JSON:

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

Output Format

Table Output (default)

Found 5 groups/channels:

ID              Type         Members    Topics   Name
----------------------------------------------------------------------
1234567890      supergroup   1500       Yes      My Community
9876543210      channel      5000       -        News Channel
...

Found 3 DMs:

ID              Type         Username             Name
------------------------------------------------------------
111222333       private      @alice               Alice Smith
444555666       private      -                    Bob Jones
...

JSON Output (--json)

[
  {
    "id": 1234567890,
    "name": "My Community",
    "type": "supergroup",
    "username": "mycommunity",
    "member_count": 1500,
    "has_topics": true
  }
]

Group Types

private - 1:1 private chats
group - Basic groups (< 200 members)
supergroup - Upgraded groups (can have topics)
channel - Broadcast channels

Forum Topics

Some supergroups have "forum topics" enabled, which is similar to Discord's channel structure. When a group has topics:

Messages are organized by topic
Use --group GROUP_ID to see available topics
Sync will pull messages from each topic separately

Exit Codes

0 - Success
1 - Authentication error
2 - Group not found or configuration error

Related Skills

telegram-init - Initialize Telegram connection
telegram-sync - Sync messages from groups
telegram-read - Read synced messages

Source

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

View on GitHub

Overview

This skill lists all accessible Telegram groups, channels, and DMs. It can also reveal forum topics for groups with topics enabled, helping users discover what's available and how to navigate their Telegram ecosystem.

How This Skill Works

The skill queries the Telegram connector to enumerate reachable groups, channels, and DMs. For groups with forum topics, it can list individual topics using the --group GROUP_ID option. Output can be presented as a human-friendly table by default or as JSON when --json is used.

When to Use It

A user asks which Telegram groups, channels, or DMs they have access to
You want to discover group topics in groups that have forums enabled
You need a machine-readable list for integration (JSON output)
You want to list groups only (exclude DMs) using --no-dms
You need to inspect topics within a specific group using --group GROUP_ID

Quick Start

Step 1: List all groups and DMs (default): python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py
Step 2: Get JSON output for automation: python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py --json
Step 3: List topics in a specific group: python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py --group 1234567890

Best Practices

Prefer JSON output (--json) for integrations or automation
Verify authentication and access permissions if results are incomplete
Use --group GROUP_ID to drill down into a group's topics when available
Use --no-dms to focus on groups when DMs are not relevant
Cross-check group types (private, group, supergroup, channel) to interpret results correctly

Example Use Cases

User: list Telegram groups. System: returns a table of groups, channels, and DMs with IDs and names
User: show my Telegram channels. System: lists only channels with IDs and usernames
User: list topics in group 1234567890. System: returns available forum topics for that group
User: list my Telegram DMs. System: shows direct chats with IDs and participant names
User: export results as JSON. System: outputs an array of objects with id, name, type, username, member_count, has_topics

Frequently Asked Questions

Add this skill to your agents