# Объекты Max Bot API

## Update

Событие, приходящее в Long Polling или на Webhook.

| Поле | Тип | Описание |
|------|-----|----------|
| update_type | string | Тип события, например `message_created`, `message_callback` |
| timestamp | int64 | Unix-время события |
| message | Message | Сообщение (для message_created и др.) |
| user_locale | string | Язык пользователя (IETF BCP 47), только в диалогах |

Для событий из группового чата или канала бот должен быть назначен администратором.

**Пример:**

```json
{
  "update_type": "message_created",
  "timestamp": 0,
  "message": { ... },
  "user_locale": "ru"
}
```

При нажатии кнопки приходит тип `message_callback`; в объекте есть данные callback (в т.ч. `callback_id` для POST /answers).

---

## NewMessageBody

Тело сообщения при отправке (POST /messages) или обновлении (POST /answers и т.п.).

| Поле | Тип | Описание |
|------|-----|----------|
| text | string | Текст до 4000 символов |
| attachments | AttachmentRequest[] | Вложения (inline_keyboard и др.) |
| link | NewMessageLink | Ссылка на сообщение |
| notify | bool | Уведомлять участников (по умолчанию true) |
| format | "markdown" \| "html" | Формат текста |

**Пример:**

```json
{
  "text": "Текст сообщения",
  "attachments": [{ "type": "inline_keyboard", "payload": { "buttons": [...] } }],
  "notify": true,
  "format": "markdown"
}
```

---

## Message

Объект сообщения (приходит в Update и в ответах API). Полное описание: [dev.max.ru/docs-api/objects/Message](https://dev.max.ru/docs-api/objects/Message).

| Поле | Тип | Описание |
|------|-----|----------|
| sender | User | Отправитель (опц.) |
| recipient | Recipient | Получатель |
| timestamp | int64 | Unix-время |
| link | LinkedMessage | Пересланное/ответное сообщение (опц.) |
| **body** | **MessageBody** | Содержимое: текст + вложения. Может быть `null`, если только пересланное |
| stat | MessageStat | Статистика (опц.) |
| url | string | Публичная ссылка на пост в канале (опц.) |

---

## MessageBody (входящее сообщение)

Содержимое сообщения при получении по Webhook или GET /updates. Источник: [Message](https://dev.max.ru/docs-api/objects/Message), [POST /uploads](https://dev.max.ru/docs-api/methods/POST/uploads).

| Поле | Тип | Описание |
|------|-----|----------|
| **text** | string | Текст сообщения или подпись к медиа. До 4000 символов. Может отсутствовать (только вложение). |
| **attachments** | array | Вложения. Каждый элемент: `{ "type": "<тип>", "payload": { ... } }`. |

### Типы вложений (attachments[].type)

По документации загрузки файлов (POST /uploads) поддерживаются типы: **`image`**, **`video`**, **`audio`**, **`file`**. Значение `photo` больше не используется — приходит как **`image`**.

| Тип | Описание | Форматы (при загрузке) |
|-----|----------|-------------------------|
| **image** | Фото/картинка | JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC |
| **video** | Видео | MP4, MOV, MKV, WEBM, MATROSKA |
| **audio** | Голос/аудио | MP3, WAV, M4A и др. |
| **file** | Документ или любой файл | Любые типы |

У видео и аудио в `payload` приходит **token** (используется в т.ч. для GET /videos/{videoToken}). У image/file — в `payload` приходят данные файла (токен или URL после обработки сервером).

### Как приходят сообщения в Webhook

- **Только текст:** `message.body.text` — строка, `message.body.attachments` — пустой или отсутствует.
- **Только голос/аудио:** `message.body.attachments` — один элемент `type: "audio"`, `payload` с токеном; `message.body.text` может быть пустым.
- **Только видео:** `message.body.attachments` — один элемент `type: "video"`, `payload` с токеном; `message.body.text` — по желанию.
- **Документ/файл:** `message.body.attachments` — элемент `type: "file"`, в `payload` — данные файла; `message.body.text` — опционально.
- **Фото (image):** `message.body.attachments` — элемент `type: "image"` (не `photo`), в `payload` — данные изображения.
- **Фото с подписью:** то же, что фото, плюс **`message.body.text`** — подпись (caption).

Пример (фото с подписью):

```json
{
  "update_type": "message_created",
  "message": {
    "sender": { ... },
    "recipient": { ... },
    "timestamp": 1234567890,
    "body": {
      "text": "Вот документ по делу",
      "attachments": [
        { "type": "image", "payload": { "token": "..." } }
      ]
    }
  }
}
```

Точную структуру `payload` для каждого типа смотри в ответах API (например, отправить боту сообщение и посмотреть тело Webhook в n8n) или в [официальной документации](https://dev.max.ru/docs-api).

---

## User, Chat

- **User:** [dev.max.ru/docs-api/objects/User](https://dev.max.ru/docs-api/objects/User)
- **Chat:** [dev.max.ru/docs-api/objects/Chat](https://dev.max.ru/docs-api/objects/Chat)

Полный список методов и объектов — в [официальной документации](https://dev.max.ru/docs-api).