This commit is contained in:
+2
-204
@@ -1,205 +1,3 @@
|
||||
# Отправка сообщений через 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`:
|
||||
- `RELAY_URL` - базовый URL **internal_relay** (все исходящие вызовы Bot API идут только через него)
|
||||
- `WEBHOOK_PORT` - порт для Telegram бота (по умолчанию 5005)
|
||||
- `WEBHOOK_URL` - URL доставки апдейтов от internal_relay к боту (доступен с машины relay; не URL, который видит Telegram напрямую)
|
||||
- `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: <секретный_токен>
|
||||
```
|
||||
|
||||
### Параметры запроса
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": 123456789,
|
||||
"message": "Текст сообщения"
|
||||
}
|
||||
```
|
||||
|
||||
### Аутентификация
|
||||
|
||||
API защищен секретным токеном, который передается в заголовке `X-API-Secret-Token`. Токен берется из переменной окружения `WEBHOOK_SECRET`.
|
||||
|
||||
### Ответы
|
||||
|
||||
**Успешная отправка (200):**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Сообщение отправлено успешно"
|
||||
}
|
||||
```
|
||||
|
||||
**Ошибка (400):**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Описание ошибки"
|
||||
}
|
||||
```
|
||||
|
||||
### Пример использования из Python
|
||||
|
||||
```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']}")
|
||||
```
|
||||
|
||||
### Пример использования из командной строки
|
||||
|
||||
```bash
|
||||
# Используя 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 запросов
|
||||
- Проверка корректности входных данных
|
||||
- Логирование всех попыток отправки для аудита
|
||||
- Обработка ошибок без раскрытия внутренней информации системы
|
||||
Документация: [`docs/telegram-messaging.md`](docs/telegram-messaging.md)
|
||||
|
||||
Reference in New Issue
Block a user