vibe-coding-cn/i18n/en/skills/04-dev-tools/telegram-dev/references/index.md

# Telegram Ecosystem Development Resource Index

## Official Documentation

### Bot API
**Main Documentation:** https://core.telegram.org/bots/api
**Description:** Complete reference documentation for the Telegram Bot API

**Core Features:**
- Sending and receiving messages
- Handling media files
- Inline mode
- Payment integration
- Webhook configuration
- Games and polls

### Mini Apps (Web Apps)
**Main Documentation:** https://core.telegram.org/bots/webapps
**Full Platform:** https://docs.telegram-mini-apps.com
**Description:** Development documentation for Telegram Mini Apps

**Core Features:**
- WebApp API
- Themes and UI controls
- Storage (Cloud/Device/Secure)
- Biometric authentication
- Location and sensors
- Payment integration

### Telegram API & MTProto
**Main Documentation:** https://core.telegram.org
**Description:** Complete Telegram protocol and client development

**Core Features:**
- MTProto protocol
- TDLib client library
- Authentication and encryption
- File operations
- Secret Chats

## Official GitHub Repositories

### Bot API Server
**Repository:** https://github.com/tdlib/telegram-bot-api
**Description:** Implementation of the Telegram Bot API server
**Features:**
- Local mode deployment
- Support for large files (up to 2000 MB)
- C++ implementation
- Based on TDLib

### Android Client
**Repository:** https://github.com/DrKLO/Telegram
**Description:** Source code for the official Android client
**Features:**
- Complete Android implementation
- Material Design
- Customizable compilation

### Desktop Client
**Repository:** https://github.com/telegramdesktop/tdesktop
**Description:** Official desktop client (Windows, macOS, Linux)
**Features:**
- Qt/C++ implementation
- Cross-platform support
- Full functionality

### Official Organization
**Organization Page:** https://github.com/orgs/TelegramOfficial/repositories
**Includes:**
- Beta versions
- Support tools
- Example code

## API Method Categories

### Update Management
- `getUpdates` - Long polling
- `setWebhook` - Set a webhook
- `deleteWebhook` - Delete a webhook
- `getWebhookInfo` - Webhook information

### Message Operations
**Sending Messages:**
- `sendMessage` - Text message
- `sendPhoto` - Photo
- `sendVideo` - Video
- `sendDocument` - Document
- `sendAudio` - Audio
- `sendVoice` - Voice
- `sendLocation` - Location
- `sendVenue` - Venue
- `sendContact` - Contact
- `sendPoll` - Poll
- `sendDice` - Dice/Darts

**Editing Messages:**
- `editMessageText` - Edit text
- `editMessageCaption` - Edit caption
- `editMessageMedia` - Edit media
- `editMessageReplyMarkup` - Edit keyboard
- `deleteMessage` - Delete a message

**Other Operations:**
- `forwardMessage` - Forward a message
- `copyMessage` - Copy a message
- `sendChatAction` - Send an action (typing...)

### File Operations
- `getFile` - Get file information
- File download URL: `https://api.telegram.org/file/bot<token>/<file_path>`
- File upload: Supports multipart/form-data
- Max file size: 50 MB (standard), 2000 MB (local Bot API)

### Inline Mode
- `answerInlineQuery` - Respond to an inline query
- Result types: article, photo, gif, video, audio, voice, document, location, venue, contact, game, sticker

### Callback Queries
- `answerCallbackQuery` - Respond to a button click
- Can display a notification or an alert

### Payments
- `sendInvoice` - Send an invoice
- `answerPreCheckoutQuery` - Pre-checkout
- `answerShippingQuery` - Shipping query
- Supported providers: Stripe, Yandex.Money, Telegram Stars

### Games
- `sendGame` - Send a game
- `setGameScore` - Set a score
- `getGameHighScores` - Get high scores

### Group Management
- `kickChatMember` / `unbanChatMember` - Ban/unban
- `restrictChatMember` - Restrict permissions
- `promoteChatMember` - Promote to admin
- `setChatTitle` / `setChatDescription` - Set chat info
- `setChatPhoto` - Set chat photo
- `pinChatMessage` / `unpinChatMessage` - Pin/unpin a message

## Mini Apps API Details

### Initialization
```javascript
const tg = window.Telegram.WebApp;
tg.ready();
tg.expand();
```

### Main Objects
- **WebApp** - Main interface
- **MainButton** - Main button
- **SecondaryButton** - Secondary button
- **BackButton** - Back button
- **SettingsButton** - Settings button
- **HapticFeedback** - Haptic feedback
- **CloudStorage** - Cloud storage
- **BiometricManager** - Biometrics
- **LocationManager** - Location services
- **Accelerometer** - Accelerometer
- **Gyroscope** - Gyroscope
- **DeviceOrientation** - Device orientation

### Event System
40+ events including:
- `themeChanged` - Theme changed
- `viewportChanged` - Viewport changed
- `mainButtonClicked` - Main button clicked
- `backButtonClicked` - Back button clicked
- `settingsButtonClicked` - Settings button clicked
- `invoiceClosed` - Payment completed
- `popupClosed` - Popup closed
- `qrTextReceived` - QR code scan result
- `clipboardTextReceived` - Clipboard text
- `writeAccessRequested` - Write access requested
- `contactRequested` - Contact requested

### Theme Parameters
```javascript
tg.themeParams = {
    bg_color,           // Background color
    text_color,         // Text color
    hint_color,         // Hint color
    link_color,         // Link color
    button_color,       // Button color
    button_text_color,  // Button text color
    secondary_bg_color, // Secondary background color
    header_bg_color,    // Header background color
    accent_text_color,  // Accent text color
    section_bg_color,   // Section background color
    section_header_text_color, // Section header text color
    subtitle_text_color,       // Subtitle color
    destructive_text_color     // Destructive action color
}
```

## Development Tools

### @BotFather Commands
The core tool for creating and managing Bots:

**Bot Management:**
- `/newbot` - Create a new Bot
- `/mybots` - Manage my Bots
- `/deletebot` - Delete a Bot
- `/token` - Regenerate a token

**Settings Commands:**
- `/setname` - Set name
- `/setdescription` - Set description
- `/setabouttext` - Set about text
- `/setuserpic` - Set user picture

**Feature Configuration:**
- `/setcommands` - Set command list
- `/setinline` - Enable inline mode
- `/setinlinefeedback` - Inline feedback
- `/setjoingroups` - Allow joining groups
- `/setprivacy` - Privacy mode

**Payments and Games:**
- `/setgamescores` - Game scores
- `/setpayments` - Configure payments

**Mini Apps:**
- `/newapp` - Create a Mini App
- `/myapps` - Manage Mini Apps
- `/setmenubutton` - Set menu button

### Getting an API ID
Visit https://my.telegram.org
1. Log in to your account
2. Go to API development tools
3. Create an application
4. Get your API ID and API Hash

## Common Python Libraries

### python-telegram-bot
```bash
pip install python-telegram-bot
```

**Features:**
- Complete Bot API wrapper
- Asynchronous and synchronous support
- Rich extensions
- Actively maintained

**Basic Example:**
```python
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text('Hello!')

app = Application.builder().token("TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.run_polling()
```

### aiogram
```bash
pip install aiogram
```

**Features:**
- Purely asynchronous
- High performance
- FSM state machine
- Middleware system

### Telethon / Pyrogram
MTProto client libraries:
```bash
pip install telethon
pip install pyrogram
```

**Uses:**
- Custom clients
- User account automation
- Full Telegram functionality

## Common Node.js Libraries

### node-telegram-bot-api
```bash
npm install node-telegram-bot-api
```

### Telegraf
```bash
npm install telegraf
```

**Features:**
- Modern
- Middleware architecture
- TypeScript support

### grammY
```bash
npm install grammy
```

**Features:**
- Lightweight
- Type-safe
- Plugin ecosystem

## Deployment Options

### Webhook Hosting
**Recommended Platforms:**
- Heroku
- AWS Lambda
- Google Cloud Functions
- Azure Functions
- Vercel
- Railway
- Render

**Requirements:**
- HTTPS support
- Publicly accessible
- Supported ports: 443, 80, 88, 8443

### Long Polling Hosting
**Recommended Platforms:**
- VPS (Vultr, DigitalOcean, Linode)
- Raspberry Pi
- Local server

**Advantages:**
- No HTTPS required
- Simple configuration
- Suitable for development and testing

## Security Best Practices

1.  **Token Security**
    -   Do not commit to Git
    -   Use environment variables
    -   Rotate tokens regularly

2.  **Data Validation**
    -   Validate initData
    -   Server-side validation
    -   Do not trust the client

3.  **Permission Control**
    -   Check user permissions
    -   Admin verification
    -   Group permissions

4.  **Rate Limiting**
    -   Implement request limits
    -   Prevent abuse
    -   Monitor for anomalies

## Debugging Tips

### Bot Debugging
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

### Mini App Debugging
```javascript
// Enable debug mode
tg.showAlert(JSON.stringify(tg.initDataUnsafe, null, 2));

// Console logs
console.log('WebApp version:', tg.version);
console.log('Platform:', tg.platform);
console.log('Theme:', tg.colorScheme);
```

### Webhook Testing
Use ngrok for local testing:
```bash
ngrok http 5000
# Set the generated https URL as the webhook
```

## Community Resources

- **Telegram Developer Group**: @BotDevelopers
- **Telegram API Discussion**: @TelegramBots
- **Mini Apps Discussion**: @WebAppChat

## Changelog

**Latest Features:**
- Paid Media
- Checklist Tasks
- Gift Conversion
- Business Features
- Poll options increased to 12
- Story publishing and editing

---

## Complete Implementation Templates (New)

### Telegram Bot Button and Keyboard Implementation Guide
**File:** `Telegram_Bot_button_and_keyboard_implementation_template.md`
**Lines:** 404
**Size:** 12 KB
**Language:** Chinese

A concise and practical guide to implementing interactive features for Telegram Bots:

**Core Content:**
- Detailed explanation of three button types (Inline/Reply/Command Menu)
- Comparison of implementations with python-telegram-bot and Telethon
- Complete code examples (ready to use)
- Project structure and modular design
- Handler priority and event handling
- Production deployment solutions
- Security and error handling best practices

**Features:**
- Concise core code, removing redundant examples
- Focus on common scenarios and practical tips
- A complete quick reference table

---

### Dynamic View Alignment - Data Display Guide
**File:** `dynamic-view-alignment-implementation-document.md`
**Lines:** 407
**Size:** 12 KB
- **Language:** Chinese

A professional solution for monospaced font data alignment and formatting:

**Core Features:**
- Intelligent dynamic view alignment algorithm (three-step method)
- Automatic column width calculation, no hardcoding required
- Smart alignment rules (text left, numbers right)
- Complete formatting system:
  - Smart abbreviation for trading volume (B/M/K)
  - Smart precision for price (adaptive decimal places)
  - Formatting for price change percentage (+/- signs)
  - Smart display for fund flow

**Use Cases:**
- Leaderboards, data tables, real-time tickers
- Any Telegram Bot that needs professional data display

**Technical Features:**
- O(n×m) linear complexity, highly efficient
- Processes 1000 rows of data in just 5-10ms
- Supports Chinese character width expansion

**Visual Effect Example:**
```
1.   BTC      $1.23B    $45,000   +5.23%
2.   ETH    $890.5M     $2,500   +3.12%
3.   SOL    $567.8M       $101   +8.45%
```

---

**These templates provide a complete solution for Telegram Bot development, from basic to production level!**