✉️ Сообщения

Отправляет текстовое сообщение. Подтверждено в бою ✅

Структура wire-запроса

Сервер ожидает вложенный объект message, а не плоские параметры:

{
  "chatId": 34540359,
  "message": {
    "cid":         1774194113898,   # уникальный client ID = int(time.time()*1000)
    "text":        "Привет!",
    "detectShare": false,
    "isLive":      false
  }
}

Форматирование текста (elements)

Параметр text принимает как строку, так и объект FormattedText. При передаче FormattedText библиотека автоматически формирует массив elements.

from maxapi.formatting import FormattedText

fmt = (FormattedText()
    .bold("Жирный")
    .add(" и ")
    .italic("курсив")
    .add(" + ")
    .link("ссылка", "https://example.com")
)
await client.send_message(chat_id, fmt)

Поддерживаемые типы форматирования (подтверждено в бою ✅):

Wire-формат elements

Массив elements передаётся внутри объекта message. Каждый элемент — это объект с полями:

{
  "type": "STRONG",        # тип форматирования
  "from": 15,              # смещение в символах (опускается если 0)
  "length": 6,            # длина диапазона
  "attributes": { ... }   # только для LINK (содержит url)
}

Пересылает сообщение в другой (или тот же) чат. Подтверждено в бою ✅

await client.forward_message(
    to_chat_id=34540359,
    from_chat_id=63530148,
    message_id=116278582161789412
)

Wire-формат пересылки

{
  "chatId": 34540359,
  "message": {
    "cid": 1774269905000,
    "text": "",
    "link": {
      "type": "FORWARD",
      "messageId": 116278505421542491,
      "chatId": 63530148
    }
  }
}

Загружает изображение на сервер и отправляет его в чат. Двухшаговый процесс: сначала получает одноразовый URL загрузки (opcode 80), потом делает HTTP multipart POST, и наконец отправляет MSG_SEND со вложением. Подтверждено в бою ✅

Протокол загрузки (два шага)

Шаг 1 — запрос одноразового URL (opcode 80 PHOTO_UPLOAD):

# Запрос
{ "chatId": 55474168, "count": 1 }

# Ответ сервера
{
  "url": "https://iu.oneme.ru/uploadImage?X-Amz-Algorithm=...",
  "photoIds": "8361541005"
}

Шаг 2 — HTTP multipart POST на полученный URL:

# Content-Type: multipart/form-data
# поле: file = <байты JPEG>, filename=photo.jpg, content_type=image/jpeg

# Ответ
{
  "photos": {
    "8361541005": { "token": "bso0sDwO...==" }
  }
}

Шаг 3 — MSG_SEND с attaches:

{
  "chatId": 55474168,
  "message": {
    "cid": 1774199151982,
    "text": "Привет от MAX",
    "detectShare": false,
    "isLive": false,
    "attaches": [
      { "_type": "PHOTO", "photoToken": "bso0sDwO...==" }
    ],
    "link": { "type": "REPLY", "messageId": 116273915609219087 }
  }
}

Ответ сервера (MSG_SEND)

{
  "chatId": 55474168,
  "message": {
    "id": 116273915651779748,
    "time": 1774199152401,
    "type": "USER",
    "sender": 61091213,
    "text": "Привет от MAX",
    "attaches": [
      {
        "_type": "PHOTO",
        "photoId": 8361541005,
        "photoToken": "bso0sDwO...==",
        "baseUrl": "https://i.oneme.ru/i?r=BTExG6...",
        "width": 1,
        "height": 1
      }
    ],
    "link": {
      "type": "REPLY",
      "message": { "id": 116273915609219087, "text": "Привет", /* ... */ },
      "chatId": 0
    }
  },
  "unread": 0
}

Пример — юзербот: отвечаем картинкой на любое сообщение

from maxapi import MaxClient, Message

client = MaxClient("my_session")

@client.on_message
async def on_message(msg: Message):
    if msg.is_outgoing:
        return
    await client.send_photo(
        msg.chat_id,
        "banner.jpg",
        caption="Привет!",
        reply_to=msg.id,
    )

Нижнеуровневый метод: загружает байты изображения и возвращает photoToken — строку, пригодную для вставки в attaches вручную. Используется внутри send_photo(), но может вызываться напрямую. Подтверждено в бою ✅

with open("photo.jpg", "rb") as f:
    data = f.read()

token = await client.upload_photo(chat_id=55474168, image_data=data)

# Вставить токен вручную в attaches
await client.send_message(
    chat_id=55474168,
    text="Смотри:",
    attaches=[{ "_type": "PHOTO", "photoToken": token }],
)

Редактирует текст уже отправленного сообщения.

await client.edit_message(
    chat_id=34540359,
    msg_id=116273301732920444,
    text="Исправленный текст"
)

Удаляет одно или несколько сообщений. Подтверждены оба режима: локальное удаление и удаление у всех ✅

await client.delete_messages(
    chat_id=34540359,
    msg_ids=[116273301732920444, 116273301732920445]
)

await client.delete_messages(
    chat_id=34540359,
    msg_ids=[116273301732920444],
    delete_for_all=True
)

Отправляет уведомление «печатает…». Запрос без ожидания ответа (wait_response=False).

await client.send_typing(chat_id=34540359)

Помечает сообщения как прочитанные (до указанного ID включительно).

Ставит реакцию на сообщение. Fire-and-forget (ответ не ожидается).

await client.react(chat_id=63530148, msg_id=1234, reaction="🤣")

Убирает реакцию с сообщения. Fire-and-forget.

await client.cancel_reaction(chat_id=63530148, msg_id=1234)

Удобная обёртка для отправки стикера. Эквивалентна send_message(chat_id, "", attaches=[…]). Подтверждено в бою ✅

r = await client.send_sticker(chat_id=63530148, sticker_id=1083866299)

Получает превью ссылки (title, description, thumbnail).

info = await client.get_link_info("https://example.com")