205 lines
8.4 KiB
Markdown
205 lines
8.4 KiB
Markdown
# Отправка сообщений через 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: <секретный_токен>
|
|
```
|
|
|
|
### Параметры запроса
|
|
|
|
```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 запросов
|
|
- Проверка корректности входных данных
|
|
- Логирование всех попыток отправки для аудита
|
|
- Обработка ошибок без раскрытия внутренней информации системы
|