7cd3ccf21c
- register_max_webhook.py, fetch_schema.py - n8n-code-node-max-normalize.js (max_id, callback из callback.user, contact из vcf_info) - n8n-code-add-menu-buttons.js (меню с callback, request_contact, Главное меню) - docs: max-webhook, max-curl-http-request, max-api (форматы, кнопки, контакт), clpr vs sprf - README, SITUATION, схемы sprf_ и clpr_, .gitignore Co-authored-by: Cursor <cursoragent@cursor.com>
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).
|