Zilant2025/TELEGRAM_MESSAGING.md

Отправка сообщений через Telegram бота

Описание

В проект добавлена возможность отправки сообщений пользователям Telegram через бота по их ID. Функциональность включает:

1. API endpoint для отправки сообщений из других скриптов
2. Интерфейс в веб-приложении для отправки сообщений через браузер
3. Обработку ошибок и логирование всех операций

Архитектура системы

Система состоит из двух основных компонентов:

• Веб-интерфейс (db_edit.py) - работает на порту 5006 (WEBCTRL_PORT)
• Telegram бот (tg_mainbot.py) - работает на порту 5005 (WEBHOOK_PORT)

API endpoint /send_message находится в Telegram боте, поэтому все запросы должны отправляться на порт 5005.

Конфигурация портов

Порты и URL настраиваются в файле .env:

• WEBHOOK_PORT - порт для Telegram бота (по умолчанию 5005)
• WEBHOOK_URL - полный URL бота (например, https://bot.aabpro.ru/testbot)
• WEBCTRL_PORT - порт для веб-интерфейса (по умолчанию 5006)

Веб-интерфейс автоматически читает URL и порт бота из переменных окружения и использует их для отправки запросов.

Использование через веб-интерфейс

В заголовке страницы "Управление постами VK и событиями" добавлены два поля:

• ID пользователя - числовой ID пользователя в Telegram
• Сообщение - текст сообщения для отправки
• Кнопка "Отправить" - отправляет сообщение через бота

Особенности интерфейса:

• Поля проверяются на заполненность перед отправкой
• ID пользователя проверяется на корректность (должен быть числом)
• Поддержка отправки по клавише Enter
• Индикатор загрузки во время отправки
• Автоматическая очистка полей после успешной отправки

Использование через API

Endpoint

POST /send_message
POST {WEBHOOK_PATH}/send_message

Где WEBHOOK_PATH - путь из переменной окружения WEBHOOK_URL (например, /testbot).

Примеры URL:

• Локально: http://localhost:5005/send_message
• Через reverse proxy: https://bot.aabpro.ru/testbot/send_message

Заголовки запроса

Content-Type: application/json
X-API-Secret-Token: <секретный_токен>

Параметры запроса

{
    "user_id": 123456789,
    "message": "Текст сообщения"
}

Аутентификация

API защищен секретным токеном, который передается в заголовке X-API-Secret-Token. Токен берется из переменной окружения WEBHOOK_SECRET.

Ответы

Успешная отправка (200):

{
    "success": true,
    "message": "Сообщение отправлено успешно"
}

Ошибка (400):

{
    "success": false,
    "error": "Описание ошибки"
}

Пример использования из Python

import requests

def send_telegram_message(user_id, message):
    # Используем внешний URL через reverse proxy
    url = "https://bot.aabpro.ru/testbot/send_message"
    data = {
        "user_id": user_id,
        "message": message
    }
    headers = {
        'Content-Type': 'application/json',
        'X-API-Secret-Token': 'ваш_секретный_токен'
    }
    
    response = requests.post(url, json=data, headers=headers)
    result = response.json()
    
    if result["success"]:
        print("Сообщение отправлено успешно!")
    else:
        print(f"Ошибка: {result['error']}")

Пример использования из командной строки

# Используя curl (через reverse proxy)
curl -X POST https://bot.aabpro.ru/testbot/send_message \
  -H "Content-Type: application/json" \
  -H "X-API-Secret-Token: ваш_секретный_токен" \
  -d '{"user_id": 123456789, "message": "Привет!"}'

# Используя curl (локально)
curl -X POST http://localhost:5005/send_message \
  -H "Content-Type: application/json" \
  -H "X-API-Secret-Token: ваш_секретный_токен" \
  -d '{"user_id": 123456789, "message": "Привет!"}'

# Используя примерный скрипт
python send_telegram_example.py 123456789 "Привет! Это тестовое сообщение."

Обработка ошибок

Система обрабатывает следующие типы ошибок:

HTTP ошибки:

1. 401 Unauthorized - Неверный или отсутствующий API токен
2. 400 Bad Request - Неверный ID пользователя или отсутствующие данные
3. 500 Internal Server Error - Внутренняя ошибка сервера

Коды ошибок API:

• INVALID_TOKEN - Неверный токен аутентификации
• NO_DATA - Отсутствуют данные в запросе
• NO_USER_ID - Не указан ID пользователя
• NO_MESSAGE - Не указан текст сообщения
• INVALID_USER_ID - user_id не является числом
• TELEGRAM_ERROR - Ошибка Telegram API
• INTERNAL_ERROR - Внутренняя ошибка сервера

Ошибки Telegram API:

1. 403 Forbidden - Пользователь заблокировал бота или не начал с ним диалог
2. 400 Bad Request - Неверный ID пользователя
3. 429 Too Many Requests - Превышен лимит отправки сообщений
4. 404 Not Found - Пользователь не найден

Диагностика в веб-интерфейсе

Веб-интерфейс предоставляет подробную диагностику ошибок:

• Время ответа сервера
• HTTP статус код
• Код ошибки API
• Конкретные предложения по решению проблемы
• Автоматическое скрытие уведомлений

Все ошибки логируются в файл логов с указанием типа ошибки и ID пользователя.

Логирование

Все операции отправки сообщений записываются в лог с указанием:

• Времени операции
• ID пользователя
• Статуса отправки (успех/ошибка)
• Краткого описания ошибки (при наличии)

Пример записи в логе:

[2024-01-15 10:30:45] [TG_bot] ИНФО: Сообщение отправлено: Привет! Это тестовое сообщение... (Пользователь user_123456789)

Требования

• Telegram бот должен быть запущен и подключен через webhook
• Пользователь должен начать диалог с ботом (отправить команду /start)
• Пользователь не должен заблокировать бота

Безопасность

• API endpoint доступен только для POST запросов
• Проверка корректности входных данных
• Логирование всех попыток отправки для аудита
• Обработка ошибок без раскрытия внутренней информации системы