MessageGateway/docs/api/message.md

# API для отправки сообщений

**Важно:** Все эндпоинты для отправки сообщений требуют API ключ в заголовке `X-API-Key`.

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

Все эндпоинты требуют API ключ в заголовке запроса:

```bash
X-API-Key: your_api_key_here
```

API ключ настраивается в переменной окружения `API_KEY` в файле `.env`.

## Отправка текстового сообщения

```bash
POST /api/v1/message/text
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "tg_group": "monitoring",
  "tg_thread_id": 0,
  "text": "<b>Критическое уведомление</b>\n\nСистема недоступна!\n\n<i>Время: 2024-02-08 16:49:44</i>",
  "parse_mode": "HTML",
  "disable_web_page_preview": false
}
```

**Пример ответа:**
```json
{
  "status": "ok",
  "message": "Сообщение отправлено в чат monitoring, тред 0"
}
```

**Поддерживаемые режимы парсинга:**
- `HTML` - HTML форматирование (рекомендуется)
- `Markdown` - Markdown форматирование
- `MarkdownV2` - Markdown V2 форматирование

**Примеры форматирования:**
- HTML: `<b>жирный</b>`, `<i>курсив</i>`, `<code>код</code>`
- Markdown: `**жирный**`, `*курсив*`, `` `код` ``

## Отправка фото

```bash
POST /api/v1/message/photo
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "tg_group": "monitoring",
  "tg_thread_id": 0,
  "photo": "https://grafana.example.com/render/dashboard-solo?panelId=1&width=1000&height=500",
  "caption": "<b>График CPU</b>\n\n<i>Время: 2024-02-08 16:49:44</i>",
  "parse_mode": "HTML"
}
```

**Пример ответа:**
```json
{
  "status": "ok",
  "message": "Фото отправлено в чат monitoring, тред 0"
}
```

**Примечания:**
- Фото может быть передано через URL (автоматически загрузится) или как файл
- Поддерживаются форматы: JPG, PNG, GIF, WebP
- Максимальный размер файла: 10 МБ (Telegram), зависит от мессенджера
- Для отправки графиков из Grafana используйте URL рендеринга дашбордов

## Отправка видео

```bash
POST /api/v1/message/video
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "tg_group": "monitoring",
  "tg_thread_id": 0,
  "video": "https://example.com/recording.webm",
  "caption": "<b>Запись работы системы</b>\n\n<i>Длительность: 60 сек</i>",
  "parse_mode": "HTML",
  "duration": 60,
  "width": 1920,
  "height": 1080
}
```

**Пример ответа:**
```json
{
  "status": "ok",
  "message": "Видео отправлено в чат monitoring, тред 0"
}
```

**Примечания:**
- Видео может быть передано через URL (автоматически загрузится) или как файл
- Поддерживаются форматы: MP4, WebM, MOV (зависит от мессенджера)
- Максимальный размер файла: 50 МБ (Telegram), зависит от мессенджера
- Длительность, ширина и высота опциональны, но рекомендуются для лучшего отображения

## Отправка аудио

```bash
POST /api/v1/message/audio
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "tg_group": "monitoring",
  "tg_thread_id": 0,
  "audio": "https://example.com/notification.ogg",
  "caption": "<b>Аудио уведомление</b>\n\n<i>Система работает нормально</i>",
  "parse_mode": "HTML",
  "duration": 30,
  "performer": "System Notification",
  "title": "Alert Notification"
}
```

**Пример ответа:**
```json
{
  "status": "ok",
  "message": "Аудио отправлено в чат monitoring, тред 0"
}
```

**Примечания:**
- Аудио может быть передано через URL (автоматически загрузится) или как файл
- Поддерживаются форматы: MP3, OGG, WAV, M4A (зависит от мессенджера)
- Максимальный размер файла: 50 МБ (Telegram), зависит от мессенджера
- Исполнитель и название опциональны, но улучшают отображение в Telegram

## Отправка документа

```bash
POST /api/v1/message/document
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "tg_group": "monitoring",
  "tg_thread_id": 0,
  "document": "https://example.com/report.xlsx",
  "caption": "<b>Отчет за неделю</b>\n\n<i>Дата: 2024-02-08</i>",
  "parse_mode": "HTML",
  "filename": "report_2024-02-08.xlsx"
}
```

**Пример ответа:**
```json
{
  "status": "ok",
  "message": "Документ отправлен в чат monitoring, тред 0"
}
```

**Примечания:**
- Документ может быть передан через URL (автоматически загрузится) или как файл
- Поддерживаются все форматы файлов (PDF, DOCX, XLSX, TXT, и т.д.)
- Максимальный размер файла: 50 МБ (Telegram), зависит от мессенджера
- Имя файла опционально, если не указано - используется имя из URL
- Для отправки отчетов используйте прямые ссылки на файлы

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

Все endpoints поддерживают параметр `messenger` (опционально):
- `?messenger=telegram` - использовать Telegram
- `?messenger=max` - использовать MAX/VK
- Если не указан, используется мессенджер из конфигурации группы

## Общие параметры

- `tg_group` - имя группы из конфигурации (config/groups.json)
- `tg_thread_id` - ID треда в группе (0 для основной группы, поддерживается только для Telegram)
- `messenger` - тип мессенджера (опционально, `telegram`, `max`, по умолчанию используется из конфигурации группы)