Интеграция с Telegram API: боты, webhook, Mini Apps и платежи

 1{
 2  "update_id": 123456789,
 3  "message": {
 4    "message_id": 42,
 5    "from": {
 6      "id": 987654321,
 7      "first_name": "Иван",
 8      "last_name": "Петров",
 9      "username": "ivan_petrov"
10    },
11    "chat": {
12      "id": 987654321,
13      "type": "private"
14    },
15    "date": 1692960000,
16    "text": "/start",
17    "entities": [
18      {"offset": 0, "length": 6, "type": "bot_command"}
19    ]
20  }
21}

 1import httpx
 2import asyncio
 3from fastapi import FastAPI, Request
 4from pydantic import BaseModel
 5from typing import Optional
 6import redis.asyncio as redis
 7import json
 8
 9app = FastAPI()
10
11# Конфигурация
12BOT_TOKEN = "your-bot-token"
13WEBHOOK_URL = "https://your-domain.com/webhook"
14REDIS_URL = "redis://localhost:6379"
15
16# Redis для хранения состояния
17redis_client = redis.from_url(REDIS_URL)
18
19
20class TelegramBot:
21    """Асинхронный клиент Telegram Bot API"""
22    
23    BASE_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"
24    
25    async def send_message(
26        self, chat_id: int, text: str,
27        reply_markup: Optional[dict] = None,
28        parse_mode: str = "HTML"
29    ) -> dict:
30        """Отправить текстовое сообщение"""
31        payload = {
32            "chat_id": chat_id,
33            "text": text,
34            "parse_mode": parse_mode
35        }
36        if reply_markup:
37            payload["reply_markup"] = reply_markup
38        
39        async with httpx.AsyncClient() as client:
40            response = await client.post(
41                f"{self.BASE_URL}/sendMessage",
42                json=payload
43            )
44            response.raise_for_status()
45            return response.json()
46    
47    async def send_photo(
48        self, chat_id: int, photo: str, caption: str = ""
49    ) -> dict:
50        """Отправить фотографию"""
51        async with httpx.AsyncClient() as client:
52            response = await client.post(
53                f"{self.BASE_URL}/sendPhoto",
54                json={
55                    "chat_id": chat_id,
56                    "photo": photo,
57                    "caption": caption,
58                    "parse_mode": "HTML"
59                }
60            )
61            response.raise_for_status()
62            return response.json()
63    
64    async def answer_callback(
65        self, callback_query_id: str, text: str = ""
66    ) -> dict:
67        """Ответить на callback-запрос (нажатие кнопки)"""
68        async with httpx.AsyncClient() as client:
69            response = await client.post(
70                f"{self.BASE_URL}/answerCallbackQuery",
71                json={
72                    "callback_query_id": callback_query_id,
73                    "text": text
74                }
75            )
76            response.raise_for_status()
77            return response.json()
78    
79    async def edit_message(
80        self, chat_id: int, message_id: int, text: str,
81        reply_markup: Optional[dict] = None
82    ) -> dict:
83        """Редактировать существующее сообщение"""
84        payload = {
85            "chat_id": chat_id,
86            "message_id": message_id,
87            "text": text,
88            "parse_mode": "HTML"
89        }
90        if reply_markup:
91            payload["reply_markup"] = reply_markup
92        
93        async with httpx.AsyncClient() as client:
94            response = await client.post(
95                f"{self.BASE_URL}/editMessageText",
96                json=payload
97            )
98            response.raise_for_status()
99            return response.json()
100    
101    async def set_webhook(self, url: str) -> dict:
102        """Установить webhook URL"""
103        async with httpx.AsyncClient() as client:
104            response = await client.post(
105                f"{self.BASE_URL}/setWebhook",
106                json={"url": url}
107            )
108            response.raise_for_status()
109            return response.json()
110
111
112bot = TelegramBot()
113
114
115# Маршруты webhook
116@app.on_event("startup")
117async def startup():
118    """Установить webhook при запуске сервера"""
119    result = await bot.set_webhook(WEBHOOK_URL)
120    print(f"Webhook установлен: {result}")
121
122
123@app.post("/webhook")
124async def webhook_handler(request: Request):
125    """Обработка входящих обновлений от Telegram"""
126    data = await request.json()
127    
128    if "message" in data:
129        await handle_message(data["message"])
130    elif "callback_query" in data:
131        await handle_callback(data["callback_query"])
132    
133    return {"ok": True}
134
135
136async def handle_message(message: dict):
137    """Обработка входящего сообщения"""
138    chat_id = message["chat"]["id"]
139    text = message.get("text", "")
140    user_id = message["from"]["id"]
141    
142    # Получаем состояние пользователя из Redis
143    state = await redis_client.get(f"user:{user_id}:state")
144    state = state.decode() if state else "idle"
145    
146    if text == "/start":
147        await handle_start(chat_id, user_id)
148    elif text == "/help":
149        await handle_help(chat_id)
150    elif state == "waiting_name":
151        await handle_name_input(chat_id, user_id, text)
152    elif state == "waiting_phone":
153        await handle_phone_input(chat_id, user_id, text)
154    else:
155        await bot.send_message(
156            chat_id,
157            "Не понял команду. Введите /help для справки."
158        )
159
160
161async def handle_start(chat_id: int, user_id: int):
162    """Обработка команды /start"""
163    # Сохраняем состояние
164    await redis_client.set(f"user:{user_id}:state", "idle")
165    
166    keyboard = {
167        "inline_keyboard": [
168            [{"text": "📝 Оставить заявку", "callback_data": "apply"}],
169            [{"text": "📞 Связаться", "callback_data": "contact"}],
170            [{"text": "❓ Помощь", "callback_data": "help"}]
171        ]
172    }
173    
174    await bot.send_message(
175        chat_id,
176        "<b>Добро пожаловать!</b>\n\n"
177        "Я помогу вам оставить заявку или связаться "
178        "с нами. Выберите действие:",
179        reply_markup=keyboard
180    )
181
182
183async def handle_callback(callback: dict):
184    """Обработка нажатия на inline-кнопку"""
185    chat_id = callback["message"]["chat"]["id"]
186    user_id = callback["from"]["id"]
187    data = callback["data"]
188    
189    await bot.answer_callback(callback["id"])
190    
191    if data == "apply":
192        await redis_client.set(
193            f"user:{user_id}:state", "waiting_name"
194        )
195        await bot.send_message(
196            chat_id,
197            "Как вас зовут? Введите имя и фамилию:"
198        )
199    elif data == "contact":
200        await bot.send_message(
201            chat_id,
202            "Свяжитесь с нами: @developer_telegrams"
203        )
204    elif data == "help":
205        await handle_help(chat_id)

 1def build_inline_keyboard(
 2    buttons: list[list[dict]],
 3    row_width: int = 2
 4) -> dict:
 5    """Построить inline-клавиатуру из списка кнопок
 6    
 7    buttons: [
 8        [{"text": "Кнопка 1", "callback_data": "btn1"}],
 9        [{"text": "Кнопка 2", "callback_data": "btn2"}]
10    ]
11    """
12    return {"inline_keyboard": buttons}
13
14
15# Пример: меню категорий с пагинацией
16async def send_categories_menu(
17    bot_client: TelegramBot,
18    chat_id: int,
19    page: int = 0,
20    per_page: int = 6
21):
22    """Отправить меню категорий с пагинацией"""
23    
24    categories = [
25        {"id": 1, "name": "👕 Одежда", "count": 320},
26        {"id": 2, "name": "👟 Обувь", "count": 180},
27        {"id": 3, "name": "👜 Сумки", "count": 95},
28        {"id": 4, "name": "⌚ Часы", "count": 67},
29        {"id": 5, "name": "💎 Украшения", "count": 145},
30        {"id": 6, "name": "🧴 Косметика", "count": 210},
31        {"id": 7, "name": "📱 Электроника", "count": 89},
32        {"id": 8, "name": "🏠 Для дома", "count": 156},
33    ]
34    
35    # Пагинация
36    start = page * per_page
37    end = start + per_page
38    page_categories = categories[start:end]
39    total_pages = -(-len(categories) // per_page)
40    
41    # Строим клавиатуру
42    keyboard_buttons = []
43    for cat in page_categories:
44        keyboard_buttons.append([{
45            "text": f"{cat['name']} ({cat['count']})",
46            "callback_data": f"category_{cat['id']}"
47        }])
48    
49    # Кнопки навигации
50    nav_row = []
51    if page > 0:
52        nav_row.append({
53            "text": "⬅️ Назад",
54            "callback_data": f"page_{page - 1}"
55        })
56    nav_row.append({
57        "text": f"{page + 1}/{total_pages}",
58        "callback_data": "noop"
59    })
60    if page < total_pages - 1:
61        nav_row.append({
62            "text": "Вперёд ➡️",
63            "callback_data": f"page_{page + 1}"
64        })
65    keyboard_buttons.append(nav_row)
66    
67    await bot_client.send_message(
68        chat_id,
69        "<b>📂 Выберите категорию:</b>",
70        reply_markup=build_inline_keyboard(keyboard_buttons)
71    )

 1async def handle_application_form(
 2    bot_client: TelegramBot,
 3    chat_id: int,
 4    user_id: int,
 5    text: str
 6):
 7    """Пошаговая обработка формы заявки"""
 8    
 9    # Получаем текущий шаг из Redis
10    step = await redis_client.get(f"user:{user_id}:step")
11    step = step.decode() if step else "name"
12    
13    # Получаем уже введённые данные
14    data_raw = await redis_client.get(f"user:{user_id}:form_data")
15    data = json.loads(data_raw) if data_raw else {}
16    
17    if step == "name":
18        data["name"] = text
19        await redis_client.set(
20            f"user:{user_id}:form_data", json.dumps(data)
21        )
22        await redis_client.set(f"user:{user_id}:step", "phone")
23        await bot_client.send_message(
24            chat_id,
25            "📱 Введите номер телефона:"
26        )
27    
28    elif step == "phone":
29        data["phone"] = text
30        await redis_client.set(
31            f"user:{user_id}:form_data", json.dumps(data)
32        )
33        await redis_client.set(f"user:{user_id}:step", "comment")
34        await bot_client.send_message(
35            chat_id,
36            "💬 Опишите вашу задачу (или введите «-»):"
37        )
38    
39    elif step == "comment":
40        data["comment"] = text if text != "-" else ""
41        
42        # Сохраняем заявку в БД
43        await save_application(user_id, data)
44        
45        # Сбрасываем состояние
46        await redis_client.delete(f"user:{user_id}:step")
47        await redis_client.delete(f"user:{user_id}:form_data")
48        await redis_client.set(f"user:{user_id}:state", "idle")
49        
50        # Подтверждение
51        await bot_client.send_message(
52            chat_id,
53            "✅ <b>Заявка принята!</b>\n\n"
54            f"👤 Имя: {data['name']}\n"
55            f"📱 Телефон: {data['phone']}\n"
56            f"💬 Комментарий: {data.get('comment', 'нет')}\n\n"
57            "Мы свяжемся с вами в течение часа!"
58        )

 1async def handle_callback_safe(
 2    bot_client: TelegramBot,
 3    callback: dict
 4):
 5    """Безопасная обработка callback с обработкой ошибок"""
 6    try:
 7        callback_id = callback["id"]
 8        data = callback["data"]
 9        chat_id = callback["message"]["chat"]["id"]
10        user_id = callback["from"]["id"]
11        
12        # Всегда отвечаем на callback (иначе "часики" висят)
13        await bot_client.answer_callback(callback_id)
14        
15        if data == "noop":
16            return  # Заглушка для кнопки-индикатора
17        
18        if data.startswith("category_"):
19            category_id = int(data.split("_")[1])
20            await show_category_items(bot_client, chat_id, category_id)
21        
22        elif data.startswith("page_"):
23            page = int(data.split("_")[1])
24            await send_categories_menu(bot_client, chat_id, page)
25        
26        elif data.startswith("order_"):
27            item_id = int(data.split("_")[1])
28            await start_order_process(bot_client, chat_id, user_id, item_id)
29        
30    except Exception as e:
31        print(f"Ошибка callback: {e}")
32        await bot_client.send_message(
33            callback["message"]["chat"]["id"],
34            "⚠️ Произошла ошибка. Попробуйте ещё раз."
35        )

 1import os
 2from pathlib import Path
 3
 4class TelegramFileHandler:
 5    """Обработка файлов от Telegram"""
 6    
 7    API_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"
 8    DOWNLOAD_URL = "https://api.telegram.org/file/bot"
 9    
10    async def download_file(self, file_id: str, 
11                             save_path: str) -> str:
12        """Скачать файл из Telegram по file_id"""
13        async with httpx.AsyncClient() as client:
14            # Получаем путь к файлу
15            response = await client.get(
16                f"{self.API_URL}/getFile",
17                params={"file_id": file_id}
18            )
19            file_info = response.json()["result"]
20            file_path = file_info["file_path"]
21            
22            # Скачиваем файл
23            response = await client.get(
24                f"{self.DOWNLOAD_URL}{BOT_TOKEN}/{file_path}"
25            )
26            
27            # Сохраняем
28            local_path = Path(save_path)
29            local_path.parent.mkdir(parents=True, exist_ok=True)
30            local_path.write_bytes(response.content)
31            
32            return str(local_path)
33    
34    async def handle_document(self, message: dict) -> dict:
35        """Обработка загруженного документа"""
36        document = message.get("document")
37        if not document:
38            return None
39        
40        file_id = document["file_id"]
41        file_name = document.get("file_name", "unknown")
42        file_size = document.get("file_size", 0)
43        
44        # Проверяем размер (макс. 20 МБ для скачивания)
45        if file_size > 20 * 1024 * 1024:
46            return {"error": "Файл слишком большой (макс. 20 МБ)"}
47        
48        # Определяем тип файла
49        ext = Path(file_name).suffix.lower()
50        allowed = [".pdf", ".doc", ".docx", ".xlsx", ".csv", ".jpg", ".png"]
51        
52        if ext not in allowed:
53            return {"error": f"Неподдерживаемый формат: {ext}"}
54        
55        # Скачиваем и сохраняем
56        save_dir = f"uploads/{message['from']['id']}"
57        save_path = f"{save_dir}/{file_name}"
58        local_path = await self.download_file(file_id, save_path)
59        
60        return {
61            "file_name": file_name,
62            "file_size": file_size,
63            "local_path": local_path,
64            "extension": ext
65        }
66    
67    async def handle_photo(self, message: dict) -> dict:
68        """Обработка загруженной фотографии"""
69        photos = message.get("photo", [])
70        if not photos:
71            return None
72        
73        # Берём фото максимального размера
74        best_photo = max(photos, key=lambda p: p.get("file_size", 0))
75        file_id = best_photo["file_id"]
76        
77        save_dir = f"uploads/{message['from']['id']}"
78        save_path = f"{save_dir}/photo_{message['message_id']}.jpg"
79        local_path = await self.download_file(file_id, save_path)
80        
81        return {
82            "file_name": f"photo_{message['message_id']}.jpg",
83            "file_size": best_photo.get("file_size", 0),
84            "local_path": local_path
85        }
86
87
88file_handler = TelegramFileHandler()
89
90
91async def handle_document_message(message: dict, 
92                                   bot_client: TelegramBot):
93    """Обработка сообщения с документом"""
94    chat_id = message["chat"]["id"]
95    
96    result = await file_handler.handle_document(message)
97    
98    if not result:
99        return
100    
101    if "error" in result:
102        await bot_client.send_message(
103            chat_id, f"⚠️ {result['error']}"
104        )
105        return
106    
107    await bot_client.send_message(
108        chat_id,
109        f"📄 <b>Файл получен!</b>\n\n"
110        f"📎 Имя: {result['file_name']}\n"
111        f"📊 Размер: {result['file_size'] // 1024} КБ\n\n"
112        f"Обрабатываю..."
113    )
114    
115    # Здесь — ваша бизнес-логика обработки файла
116    # Например, парсинг CSV, распознавание PDF и т.д.

 1async def broadcast_with_file(
 2    bot_client: TelegramBot,
 3    user_ids: list[int],
 4    text: str,
 5    file_path: str
 6):
 7    """Массовая рассылка сообщения с файлом"""
 8    success = 0
 9    failed = 0
10    
11    for user_id in user_ids:
12        try:
13            # Отправляем текст
14            await bot_client.send_message(user_id, text)
15            
16            # Отправляем файл
17            async with httpx.AsyncClient() as client:
18                with open(file_path, "rb") as f:
19                    await client.post(
20                        f"{bot_client.BASE_URL}/sendDocument",
21                        data={"chat_id": user_id},
22                        files={"document": f}
23                    )
24            
25            success += 1
26            await asyncio.sleep(0.05)  # 20 сообщ/сек
27            
28        except Exception as e:
29            failed += 1
30            print(f"Ошибка отправки {user_id}: {e}")
31    
32    print(f"Рассылка: {success} успешно, {failed} ошибок")

 1async def send_invoice(
 2    bot_client: TelegramBot,
 3    chat_id: int,
 4    product_name: str,
 5    description: str,
 6    price_rub: int,
 7    payload: str
 8):
 9    """Отправить счёт на оплату"""
10    
11    # Цена в копейках × 100 (Telegram использует минимальные единицы)
12    prices = [
13        {
14            "label": product_name,
15            "amount": price_rub * 100  # В копейках
16        }
17    ]
18    
19    invoice = {
20        "chat_id": chat_id,
21        "title": product_name,
22        "description": description,
23        "payload": payload,
24        "provider_token": "your-provider-token",
25        "currency": "RUB",
26        "prices": prices,
27        "start_parameter": "pay",
28        "need_email": True,
29        "send_email_to_provider": True
30    }
31    
32    async with httpx.AsyncClient() as client:
33        response = await client.post(
34            f"{bot_client.BASE_URL}/sendInvoice",
35            json=invoice
36        )
37        response.raise_for_status()
38        return response.json()
39
40
41async def handle_pre_checkout(pre_checkout: dict):
42    """Обработка pre-checkout запроса (перед оплатой)"""
43    # Проверяем наличие товара, валидность заказа
44    order_id = pre_checkout["invoice_payload"]
45    
46    # Проверяем, не истёк ли счёт
47    order = await get_order(order_id)
48    if not order or order["status"] == "expired":
49        await bot.answer_pre_checkout_query(
50            pre_checkout_query_id=pre_checkout["id"],
51            ok=False,
52            error_message="Счёт истёк. Оформите заказ заново."
53        )
54        return
55    
56    # Подтверждаем оплату
57    await bot.answer_pre_checkout_query(
58        pre_checkout_query_id=pre_checkout["id"],
59        ok=True
60    )
61
62
63async def handle_successful_payment(message: dict):
64    """Обработка успешной оплаты"""
65    payment = message["successful_payment"]
66    chat_id = message["chat"]["id"]
67    user_id = message["from"]["id"]
68    
69    # Сохраняем данные об оплате
70    await save_payment({
71        "user_id": user_id,
72        "order_id": payment["invoice_payload"],
73        "total_amount": payment["total_amount"],
74        "currency": payment["currency"],
75        "telegram_payment_id": payment["telegram_payment_charge_id"],
76    })
77    
78    # Отправляем подтверждение
79    await bot.send_message(
80        chat_id,
81        "✅ <b>Оплата получена!</b>\n\n"
82        f"💰 Сумма: {payment['total_amount'] / 100} "
83        f"{payment['currency']}\n"
84        f"🆔 Заказ: {payment['invoice_payload']}\n\n"
85        "Спасибо за покупку! Детали заказа отправлены "
86        "на вашу почту."
87    )

 1from fastapi import FastAPI, Request
 2from fastapi.staticfiles import StaticFiles
 3from fastapi.responses import HTMLResponse
 4import hashlib
 5import hmac
 6import json
 7from urllib.parse import unquote
 8
 9app = FastAPI()
10
11BOT_TOKEN = "your-bot-token"
12
13def validate_init_data(init_data: str) -> dict:
14    """Валидация данных, переданных из Mini App
15    
16    Telegram подписывает данные HMAC-SHA256.
17    Нужно проверить подпись для безопасности.
18    """
19    # Парсим строку
20    data_dict = {}
21    for item in init_data.split("&"):
22        key, value = item.split("=", 1)
23        if key != "hash":
24            data_dict[key] = unquote(value)
25    
26    # Сортируем и формируем строку для проверки
27    data_check_string = "\n".join(
28        f"{k}={v}" for k, v in sorted(data_dict.items())
29    )
30    
31    # Вычисляем HMAC
32    secret_key = hmac.new(
33        b"WebAppData", BOT_TOKEN.encode(), hashlib.sha256
34    ).digest()
35    
36    computed_hash = hmac.new(
37        secret_key, data_check_string.encode(), hashlib.sha256
38    ).hexdigest()
39    
40    # Проверяем подпись
41    if computed_hash != data_dict.get("hash"):
42        raise ValueError("Invalid init_data signature")
43    
44    # Извлекаем данные пользователя
45    user_data = json.loads(data_dict.get("user", "{}"))
46    return user_data
47
48
49@app.post("/api/miniapp/order")
50async def create_miniapp_order(request: Request):
51    """Создать заказ из Mini App"""
52    body = await request.json()
53    init_data = request.headers.get("X-Telegram-Init-Data", "")
54    
55    # Валидируем данные из Telegram
56    user = validate_init_data(init_data)
57    
58    order = {
59        "user_id": user["id"],
60        "username": user.get("username"),
61        "first_name": user.get("first_name"),
62        "items": body["items"],
63        "total": body["total"],
64        "delivery": body.get("delivery", "pickup")
65    }
66    
67    # Сохраняем заказ
68    order_id = await save_order(order)
69    
70    return {"order_id": order_id, "status": "created"}

 1// src/App.jsx — Telegram Mini App на React
 2import { useEffect, useState } from 'react';
 3
 4// Telegram WebApp SDK
 5const tg = window.Telegram.WebApp;
 6
 7function App() {
 8    const [items, setItems] = useState([]);
 9    const [cart, setCart] = useState([]);
10
11    useEffect(() => {
12        // Инициализация Mini App
13        tg.ready();
14        tg.expand();
15        
16        // Установить тему
17        document.body.style.backgroundColor = 
18            tg.colorScheme === 'dark' ? '#1a1a1a' : '#ffffff';
19    }, []);
20
21    const addToCart = (item) => {
22        setCart([...cart, item]);
23        tg.HapticFeedback.impactOccurred('light');
24    };
25
26    const checkout = async () => {
27        const initData = tg.initData;
28        
29        const response = await fetch('/api/miniapp/order', {
30            method: 'POST',
31            headers: {
32                'Content-Type': 'application/json',
33                'X-Telegram-Init-Data': initData,
34            },
35            body: JSON.stringify({
36                items: cart,
37                total: cart.reduce((s, i) => s + i.price, 0)
38            })
39        });
40        
41        const result = await response.json();
42        
43        // Закрыть Mini App и передать данные боту
44        tg.close();
45    };
46
47    return (
48        <div className="catalog">
49            {items.map(item => (
50                <div key={item.id} className="card">
51                    <h3>{item.name}</h3>
52                    <p>{item.price} ₽</p>
53                    <button onClick={() => addToCart(item)}>
54                        В корзину
55                    </button>
56                </div>
57            ))}
58            {cart.length > 0 && (
59                <button onClick={checkout} className="checkout">
60                    Оформить ({cart.length} товаров)
61                </button>
62            )}
63        </div>
64    );
65}

 1@app.get("/api/catalog")
 2async def get_catalog(
 3    category: str = None,
 4    size: str = None,
 5    min_price: int = None,
 6    max_price: int = None,
 7    page: int = 1,
 8    per_page: int = 12
 9):
10    """Получить каталог товаров с фильтрами"""
11    query = select(Product).where(Product.is_active == True)
12    
13    if category:
14        query = query.where(Product.category == category)
15    if size:
16        query = query.where(Product.sizes.contains(size))
17    if min_price:
18        query = query.where(Product.price >= min_price)
19    if max_price:
20        query = query.where(Product.price <= max_price)
21    
22    # Пагинация
23    offset = (page - 1) * per_page
24    query = query.offset(offset).limit(per_page)
25    
26    result = await db.execute(query)
27    products = result.scalars().all()
28    
29    # Общее количество
30    count_query = select(func.count(Product.id))
31    total = (await db.execute(count_query)).scalar()
32    
33    return {
34        "items": [
35            {
36                "id": p.id,
37                "name": p.name,
38                "price": p.price,
39                "image": p.image_url,
40                "sizes": p.sizes,
41                "category": p.category
42            }
43            for p in products
44        ],
45        "total": total,
46        "page": page,
47        "pages": -(-total // per_page)
48    }