# telegram-client

> Send messages via Telegram using Telethon library with user (QR login) or bot token authentication.
Use when Claude needs to: (1) send notifications or messages to Telegram users/channels,
(2) set up a Telegram session for programmatic access, (3) integrate Telegram messaging into workflows.
Supports both personal accounts (QR code auth) and bot accounts (token auth).

- Author: darklion84
- Repository: darklion84/LocalDesk-Skills
- Version: 20260125011849
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/darklion84/LocalDesk-Skills
- Web: https://mule.run/skillshub/@@darklion84/LocalDesk-Skills~telegram-client:20260125011849

---

---
name: telegram-client
description: |
  Send messages via Telegram using Telethon library with user (QR login) or bot token authentication.
  Use when Claude needs to: (1) send notifications or messages to Telegram users/channels,
  (2) set up a Telegram session for programmatic access, (3) integrate Telegram messaging into workflows.
  Supports both personal accounts (QR code auth) and bot accounts (token auth).
license: MIT License. See LICENSE.txt for complete terms.
---

# Telegram Client

Send messages to Telegram users and channels using the Telethon library.

## Setup

1. **Create `telegram_agent.env`** in the same folder as this file:
   ```env
   TG_API_ID=your_api_id
   TG_API_HASH=your_api_hash
   TG_BOT_TOKEN=your_bot_token  # optional, for bot auth
   ```
   Remind user to get these API credentials from https://my.telegram.org/apps

2. **Install dependencies**:
   ```bash
   pip install telethon python-dotenv qrcode[pil]
   ```

## Commands

Run scripts from this file's directory.

### Initialize Session

Run this script from this file's directory:
```bash
python scripts/telegram_client.py init_session
```

**What happens:**
- If `TG_BOT_TOKEN` is set → automatic bot authentication
- Otherwise → QR code authentication (see below)

**QR Code Authentication Process:**
1. Script generates QR code image (`telegram_qr_login.png`) in this skill's directory
2. Image automatically opens in default image viewer
3. User must scan QR code with Telegram app on phone (Settings → Devices → Link Desktop Device)
4. Script waits up to 5 minutes for user to scan
5. After successful login, QR image is deleted
6. Session file (`telegram_session.session`) is created in this skill's directory

**IMPORTANT for agent:** After running `init_session`, inform user that:
- A QR code image has been opened
- They need to scan it with Telegram app on their phone
- They have 5 minutes to complete the scan
- Wait for the command to complete before proceeding

If QR image fails to open, the script will try to open the login URL in browser as fallback.

### Send Message

Run this script from this file's directory:
```bash
python scripts/telegram_client.py send_message <username> "<text>"
```

**Arguments:**
- `username` — Telegram username without `@` (e.g., `durov`)
- `text` — message text

**Example:**
```bash
python scripts/telegram_client.py send_message myuser "Hello from LocalDesk!"
```

**Note:** Session must be initialized first. If no session exists, the script will trigger QR login.

## Workflow

**IMPORTANT:** Do NOT manually check for files. Just run the scripts — they will check everything and provide clear error messages if something is missing.

1. Run `init_session` to create a session
   - If env file is missing, script will print instructions for user to create it
   - If session exists, script will use it
2. Run `send_message` to send messages

## Limitations

- Text messages only (no media/files)
- Bot accounts can only message users who started conversation with the bot
- QR login requires user interaction (scan with phone)
- Session expires if not used for extended period — re-run `init_session`