132 lines
6.2 KiB
Markdown
132 lines
6.2 KiB
Markdown
|
# Объекты 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).
|