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

760 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
name: telegram-dev
description: A full-stack guide to Telegram ecosystem development - covering Bot API, Mini Apps (Web Apps), and MTProto client development. Includes complete development resources for message handling, payments, inline mode, webhooks, authentication, storage, sensor APIs, and more.
---
# Telegram Ecosystem Development Skill
A comprehensive guide to Telegram development, covering the full technology stack for Bot development, Mini Apps (Web Apps), and client development.
## When to Use This Skill
Use this skill when you need help with the following:
- Developing a Telegram Bot (message bot)
- Creating Telegram Mini Apps
- Building a custom Telegram client
- Integrating Telegram payments and business features
- Implementing webhooks and long polling
- Using Telegram authentication and storage
- Handling messages, media, and files
- Implementing inline mode and keyboards
## Overview of the Telegram Development Ecosystem
### Three Core APIs
1. **Bot API** - For creating bot programs
- Simple to use HTTP interface
- Automatically handles encryption and communication
- Suitable for: chatbots, automation tools
2. **Mini Apps API** (Web Apps) - For creating web applications
- JavaScript interface
- Runs inside Telegram
- Suitable for: mini-apps, games, e-commerce
3. **Telegram API & TDLib** - For creating clients
- Full implementation of the Telegram protocol
- Supports all platforms
- Suitable for: custom clients, enterprise applications
## Bot API Development
### Quick Start
**API Endpoint:**
```
https://api.telegram.org/bot<TOKEN>/METHOD_NAME
```
**Get a Bot Token:**
1. Talk to @BotFather
2. Send `/newbot`
3. Follow the prompts to set a name
4. Get the token
**First Bot (Python):**
```python
import requests
BOT_TOKEN = "your_bot_token_here"
API_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"
# Send a message
def send_message(chat_id, text):
url = f"{API_URL}/sendMessage"
data = {"chat_id": chat_id, "text": text}
return requests.post(url, json=data)
# Get updates (long polling)
def get_updates(offset=None):
url = f"{API_URL}/getUpdates"
params = {"offset": offset, "timeout": 30}
return requests.get(url, params=params).json()
# Main loop
offset = None
while True:
updates = get_updates(offset)
for update in updates.get("result", []):
chat_id = update["message"]["chat"]["id"]
text = update["message"]["text"]
# Reply to the message
send_message(chat_id, f"You said: {text}")
offset = update["update_id"] + 1
```
### Core API Methods
**Update Management:**
- `getUpdates` - Get updates via long polling
- `setWebhook` - Set a webhook
- `deleteWebhook` - Delete a webhook
- `getWebhookInfo` - Query webhook status
**Message Operations:**
- `sendMessage` - Send a text message
- `sendPhoto` / `sendVideo` / `sendDocument` - Send media
- `sendAudio` / `sendVoice` - Send audio
- `sendLocation` / `sendVenue` - Send a location
- `editMessageText` - Edit a message
- `deleteMessage` - Delete a message
- `forwardMessage` / `copyMessage` - Forward/copy a message
**Interactive Elements:**
- `sendPoll` - Send a poll (up to 12 options)
- Inline Keyboard (InlineKeyboardMarkup)
- Reply Keyboard (ReplyKeyboardMarkup)
- `answerCallbackQuery` - Respond to a callback query
**File Operations:**
- `getFile` - Get file information
- `downloadFile` - Download a file
- Supports files up to 2GB (in local Bot API mode)
**Payment Features:**
- `sendInvoice` - Send an invoice
- `answerPreCheckoutQuery` - Process a payment
- Telegram Stars payment (up to 10,000 Stars)
### Webhook Configuration
**Set a Webhook:**
```python
import requests
BOT_TOKEN = "your_token"
WEBHOOK_URL = "https://yourdomain.com/webhook"
requests.post(
f"https://api.telegram.org/bot{BOT_TOKEN}/setWebhook",
json={"url": WEBHOOK_URL}
)
```
**Flask Webhook Example:**
```python
from flask import Flask, request
import requests
app = Flask(__name__)
BOT_TOKEN = "your_token"
@app.route('/webhook', methods=['POST'])
def webhook():
update = request.get_json()
chat_id = update["message"]["chat"]["id"]
text = update["message"]["text"]
# Send a reply
requests.post(
f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
json={"chat_id": chat_id, "text": f"Received: {text}"}
)
return "OK"
if __name__ == '__main__':
app.run(port=5000)
```
**Webhook Requirements:**
- Must use HTTPS
- Supports TLS 1.2+
- Ports: 443, 80, 88, 8443
- Publicly accessible URL
### Inline Keyboard
**Create an Inline Keyboard:**
```python
def send_inline_keyboard(chat_id):
keyboard = {
"inline_keyboard": [
[
{"text": "Button 1", "callback_data": "btn1"},
{"text": "Button 2", "callback_data": "btn2"}
],
[
{"text": "Open Link", "url": "https://example.com"}
]
]
}
requests.post(
f"{API_URL}/sendMessage",
json={
"chat_id": chat_id,
"text": "Choose an option:",
"reply_markup": keyboard
}
)
```
**Handle Callbacks:**
```python
def handle_callback_query(callback_query):
query_id = callback_query["id"]
data = callback_query["data"]
chat_id = callback_query["message"]["chat"]["id"]
# Respond to the callback
requests.post(
f"{API_URL}/answerCallbackQuery",
json={"callback_query_id": query_id, "text": f"You clicked {data}"}
)
# Update the message
requests.post(
f"{API_URL}/editMessageText",
json={
"chat_id": chat_id,
"message_id": callback_query["message"]["message_id"],
"text": f"You chose: {data}"
}
)
```
### Inline Mode
**Configure Inline Mode:**
Talk to @BotFather and send `/setinline`
**Handle Inline Queries:**
```python
def handle_inline_query(inline_query):
query_id = inline_query["id"]
query_text = inline_query["query"]
# Create results
results = [
{
"type": "article",
"id": "1",
"title": "Result 1",
"input_message_content": {
"message_text": f"You searched for: {query_text}"
}
}
]
requests.post(
f"{API_URL}/answerInlineQuery",
json={"inline_query_id": query_id, "results": results}
)
```
## Mini Apps (Web Apps) Development
### Initialize a Mini App
**HTML Template:**
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<title>My Mini App</title>
</head>
<body>
<h1>Telegram Mini App</h1>
<button id="mainBtn">Main Button</button>
<script>
// Get the Telegram WebApp object
const tg = window.Telegram.WebApp;
// Notify Telegram that the app is ready
tg.ready();
// Expand to full screen
tg.expand();
// Display user information
const user = tg.initDataUnsafe?.user;
if (user) {
console.log("Username:", user.first_name);
console.log("User ID:", user.id);
}
// Configure the main button
tg.MainButton.text = "Submit";
tg.MainButton.show();
tg.MainButton.onClick(() => {
// Send data to the Bot
tg.sendData(JSON.stringify({action: "submit"}));
});
// Add a back button
tg.BackButton.show();
tg.BackButton.onClick(() => {
tg.close();
});
</script>
</body>
</html>
```
### Mini App Core API
**WebApp Object Main Properties:**
```javascript
// Initialization data
tg.initData // Raw initialization string
tg.initDataUnsafe // Parsed object
// User and theme
tg.initDataUnsafe.user // User information
tg.themeParams // Theme colors
tg.colorScheme // 'light' or 'dark'
// Status
tg.isExpanded // Whether it's full screen
tg.isFullscreen // Whether it's full screen
tg.viewportHeight // Viewport height
tg.platform // Platform type
// Version
tg.version // WebApp version
```
**Main Methods:**
```javascript
// Window control
tg.ready() // Mark the app as ready
tg.expand() // Expand to full height
tg.close() // Close the Mini App
tg.requestFullscreen() // Request full screen
// Data sending
tg.sendData(data) // Send data to the Bot
// Navigation
tg.openLink(url) // Open an external link
tg.openTelegramLink(url) // Open a Telegram link
// Dialogs
tg.showPopup(params, callback) // Show a popup
tg.showAlert(message) // Show an alert
tg.showConfirm(message) // Show a confirmation
// Sharing
tg.shareMessage(message) // Share a message
tg.shareUrl(url) // Share a link
```
### UI Controls
**Main Button (MainButton):**
```javascript
tg.MainButton.setText("Click Me");
tg.MainButton.show();
tg.MainButton.enable();
tg.MainButton.showProgress(); // Show loading
tg.MainButton.hideProgress();
tg.MainButton.onClick(() => {
console.log("Main button clicked");
});
```
**Secondary Button (SecondaryButton):**
```javascript
tg.SecondaryButton.setText("Cancel");
tg.SecondaryButton.show();
tg.SecondaryButton.onClick(() => {
tg.close();
});
```
**Back Button (BackButton):**
```javascript
tg.BackButton.show();
tg.BackButton.onClick(() => {
// Back logic
});
```
**Haptic Feedback:**
```javascript
tg.HapticFeedback.impactOccurred('light'); // light, medium, heavy
tg.HapticFeedback.notificationOccurred('success'); // success, warning, error
tg.HapticFeedback.selectionChanged();
```
### Storage API
**Cloud Storage:**
```javascript
// Save data
tg.CloudStorage.setItem('key', 'value', (error, success) => {
if (success) console.log('Saved successfully');
});
// Get data
tg.CloudStorage.getItem('key', (error, value) => {
console.log('Value:', value);
});
// Delete data
tg.CloudStorage.removeItem('key');
// Get all keys
tg.CloudStorage.getKeys((error, keys) => {
console.log('All keys:', keys);
});
```
**Local Storage:**
```javascript
// Normal local storage
localStorage.setItem('key', 'value');
const value = localStorage.getItem('key');
// Secure storage (requires biometrics)
tg.SecureStorage.setItem('secret', 'value', callback);
tg.SecureStorage.getItem('secret', callback);
```
### Biometric Authentication
```javascript
const bioManager = tg.BiometricManager;
// Initialize
bioManager.init(() => {
if (bioManager.isInited) {
console.log('Supported type:', bioManager.biometricType);
// 'finger', 'face', 'unknown'
if (bioManager.isAccessGranted) {
// Already authorized, can be used
} else {
// Request authorization
bioManager.requestAccess({reason: 'Need to verify identity'}, (success) => {
if (success) {
console.log('Authorization successful');
}
});
}
}
});
// Perform authentication
bioManager.authenticate({reason: 'Confirm action'}, (success, token) => {
if (success) {
console.log('Authentication successful, token:', token);
}
});
```
### Location and Sensors
**Get Location:**
```javascript
tg.LocationManager.init(() => {
if (tg.LocationManager.isInited) {
tg.LocationManager.getLocation((location) => {
console.log('Latitude:', location.latitude);
console.log('Longitude:', location.longitude);
});
}
});
```
**Accelerometer:**
```javascript
tg.Accelerometer.start({refresh_rate: 100}, (started) => {
if (started) {
tg.Accelerometer.onEvent((event) => {
console.log('Acceleration:', event.x, event.y, event.z);
});
}
});
// Stop
tg.Accelerometer.stop();
```
**Gyroscope:**
```javascript
tg.Gyroscope.start({refresh_rate: 100}, callback);
tg.Gyroscope.onEvent((event) => {
console.log('Rotation speed:', event.x, event.y, event.z);
});
```
**Device Orientation:**
```javascript
tg.DeviceOrientation.start({refresh_rate: 100}, callback);
tg.DeviceOrientation.onEvent((event) => {
console.log('Orientation:', event.absolute, event.alpha, event.beta, event.gamma);
});
```
### Payment Integration
**Initiate a Payment (Telegram Stars):**
```javascript
tg.openInvoice('https://t.me/$invoice_link', (status) => {
if (status === 'paid') {
console.log('Payment successful');
} else if (status === 'cancelled') {
console.log('Payment cancelled');
} else if (status === 'failed') {
console.log('Payment failed');
}
});
```
### Data Validation
**Server-side Validation of initData (Python):**
```python
import hmac
import hashlib
from urllib.parse import parse_qs
def validate_init_data(init_data, bot_token):
# Parse the data
parsed = parse_qs(init_data)
received_hash = parsed.get('hash', [''])[0]
# Remove the hash
data_check_arr = []
for key, value in parsed.items():
if key != 'hash':
data_check_arr.append(f"{key}={value[0]}")
# Sort
data_check_arr.sort()
data_check_string = '\n'.join(data_check_arr)
# Calculate the secret key
secret_key = hmac.new(
b"WebAppData",
bot_token.encode(),
hashlib.sha256
).digest()
# Calculate the hash
calculated_hash = hmac.new(
secret_key,
data_check_string.encode(),
hashlib.sha256
).hexdigest()
return calculated_hash == received_hash
```
### Launching a Mini App
**From a Keyboard Button:**
```python
keyboard = {
"keyboard": [[
{
"text": "Open App",
"web_app": {"url": "https://yourdomain.com/app"}
}
]],
"resize_keyboard": True
}
requests.post(
f"{API_URL}/sendMessage",
json={
"chat_id": chat_id,
"text": "Click the button to open the app",
"reply_markup": keyboard
}
)
```
**From an Inline Button:**
```python
keyboard = {
"inline_keyboard": [[
{
"text": "Launch App",
"web_app": {"url": "https://yourdomain.com/app"}
}
]]
}
```
**From the Menu Button:**
Talk to @BotFather:
```
/setmenubutton
→ Choose your Bot
→ Provide URL: https://yourdomain.com/app
```
## Client Development (TDLib)
### Using TDLib
**Python Example (python-telegram):**
```python
from telegram.client import Telegram
tg = Telegram(
api_id='your_api_id',
api_hash='your_api_hash',
phone='+1234567890',
database_encryption_key='changeme1234',
)
tg.login()
# Send a message
result = tg.send_message(
chat_id=123456789,
text='Hello from TDLib!'
)
# Get chat list
result = tg.get_chats()
result.wait()
chats = result.update
print(chats)
tg.stop()
```
### MTProto Protocol
**Features:**
- End-to-end encryption
- High performance
- Supports all Telegram features
- Requires API ID/Hash (from https://my.telegram.org)
## Best Practices
### Bot Development
1. **Error Handling**
```python
try:
response = requests.post(url, json=data, timeout=10)
response.raise_for_status()
except requests.exceptions.RequestException as e:
print(f"Request failed: {e}")
```
2. **Rate Limiting**
- Group messages: max 20/minute
- Private messages: max 30/second
- Global limits: avoid being too frequent
3. **Use Webhooks instead of Long Polling**
- More efficient
- Lower latency
- Better scalability
4. **Data Validation**
- Always validate initData
- Don't trust client-side data
- Server-side validation for all operations
### Mini Apps Development
1. **Responsive Design**
```javascript
// Listen for theme changes
tg.onEvent('themeChanged', () => {
document.body.style.backgroundColor = tg.themeParams.bg_color;
});
// Listen for viewport changes
tg.onEvent('viewportChanged', () => {
console.log('New height:', tg.viewportHeight);
});
```
2. **Performance Optimization**
- Minimize JavaScript bundle size
- Use lazy loading
- Optimize images and resources
3. **User Experience**
- Adapt to dark/light themes
- Use native UI controls (MainButton, etc.)
- Provide haptic feedback
- Respond quickly to user actions
4. **Security Considerations**
- HTTPS is mandatory
- Validate initData
- Don't store sensitive information on the client
- Use SecureStorage for secrets
## Common Libraries and Tools
### Python
- `python-telegram-bot` - A powerful Bot framework
- `aiogram` - An asynchronous Bot framework
- `telethon` / `pyrogram` - MTProto clients
### Node.js
- `node-telegram-bot-api` - Bot API wrapper
- `telegraf` - Modern Bot framework
- `grammy` - Lightweight framework
### Other Languages
- PHP: `telegram-bot-sdk`
- Go: `telegram-bot-api`
- Java: `TelegramBots`
- C#: `Telegram.Bot`
## Reference Resources
### Official Documentation
- Bot API: https://core.telegram.org/bots/api
- Mini Apps: https://core.telegram.org/bots/webapps
- Mini Apps Platform: https://docs.telegram-mini-apps.com
- Telegram API: https://core.telegram.org
### GitHub Repositories
- Bot API Server: https://github.com/tdlib/telegram-bot-api
- Android Client: https://github.com/DrKLO/Telegram
- Desktop Client: https://github.com/telegramdesktop/tdesktop
- Official Organization: https://github.com/orgs/TelegramOfficial/repositories
### Tools
- @BotFather - Create and manage Bots
- https://my.telegram.org - Get API ID/Hash
- Telegram Web App test environment
## Reference Files
This skill includes a detailed index of Telegram development resources and complete implementation templates:
- **index.md** - A complete index of resources and quick navigation
- **Telegram_Bot_按钮和键盘实现模板.md** - An implementation guide for interactive buttons and keyboards (404 lines, 12 KB)
- Detailed explanation of three button types (Inline/Reply/Command Menu)
- Comparison of implementations with python-telegram-bot and Telethon
- Complete ready-to-use code examples and project structure
- Handler system, error handling, and deployment方案
- **动态视图对齐实现文档.md** - A guide to data display in Telegram (407 lines, 12 KB)
- Intelligent dynamic alignment algorithm (three-step method, O(n×m) complexity)
- Perfect alignment solution for monospaced font environments
- Intelligent numerical formatting system (automatic B/M/K abbreviation)
- Professional display for leaderboards and data tables
These concise guides provide core solutions for Telegram Bot development:
- All implementation methods for button and keyboard interaction
- Professional formatting and display of messages and data
- Practical best practices and quick references
---
**Master full-stack development of the Telegram ecosystem with this skill!**