maxbot

Библиотека находится в разработке, доступен не весь функционал!

Rust-библиотека для создания ботов на платформе MAX
API: https://dev.max.ru/docs-api

Библиотека предоставляет удобный, асинхронный и типобезопасный интерфейс ко всем методам API MAX: отправка сообщений (с разбиением длинного текста), загрузка файлов, управление чатами и участниками, inline-клавиатуры, обработка callback-запросов, webhook/long polling и многое другое.

Важно: API MAX доступен только для российских юридических лиц и индивидуальных предпринимателей. Для получения токена бота обратитесь к документации MAX.

📦 Установка

Добавьте в Cargo.toml:

[dependencies]
maxbot = "0.1.0"
tokio = { version = "1", features = ["full"] }

🚀 Быстрый старт

1. Создайте клиент

use maxbot_rs::MaxClient;

let token = std::env::var("MAXBOT_TOKEN").expect("Токен не найден");
let client = MaxClient::new(token);

2. Отправьте простое сообщение (Builder)

use maxbot_rs::{MaxClient, SendMessageParamsBuilder};

let mids = client.send_message_builder(
    SendMessageParamsBuilder::new()
        .text("Привет, чат!")
        .chat_id(chat_id)
).await?;
println!("Сообщение отправлено, ID: {:?}", mids);

3. Отправьте сообщение с inline-клавиатурой и обработайте нажатие

use maxbot_rs::{
    MaxClient, SendMessageParamsBuilder, Attachment,
    InlineKeyboardBuilder, InlineKeyboardButton, GetUpdatesParams,
};

// Отправка сообщения с клавиатурой
let keyboard = InlineKeyboardBuilder::new()
    .button(InlineKeyboardButton::link("е1.ru", "https://www.e1.ru"))
    .button(InlineKeyboardButton::callback("Щёлк!", "my_payload"))
    .build();

let mids = client.send_message_builder(
    SendMessageParamsBuilder::new()
        .text("Выбери действие:")
        .chat_id(chat_id)
        .attachment(Attachment::inline_keyboard(keyboard))
).await?;

// Ожидание callback
let params = GetUpdatesParams {
    marker: None,
    limit: Some(10),
    timeout: Some(30),
    types: vec!["message_callback".to_string()],
};
let (updates, _) = client.get_updates(params).await?;
for update in updates {
    if let Some(cb) = update.callback {
        // Ответ на нажатие: заменяем сообщение и показываем уведомление
        client.answer_callback_query(&cb.callback_id, new_message_json, Some("Нажато!")).await?;
    }
}

4. Отправка файла (изображения, видео, аудио, документа)

use maxbot_rs::{Attachment, SendMessageParamsBuilder};

let builder = SendMessageParamsBuilder::new()
    .text("Вот изображение")
    .chat_id(chat_id)
    .attachment(Attachment::image_local("cat.jpg"));

client.send_message_builder(builder).await?;

📚 Полная документация API

Все методы сгруппированы в impl MaxClient:

Все методы асинхронны, используют reqwest и автоматически соблюдают лимит 30 запросов в секунду (rate limiting). Длинные тексты разбиваются на фрагменты до 4000 символов с сохранением целостности слов и предложений.

🧪 Примеры

Полные примеры в папке examples/:

• me_demo.rs – информация о боте
• send_text_demo.rs – отправка текста
• send_long_text_demo.rs – разбиение длинного текста
• send_file_demo.rs – отправка изображения
• send_video_demo.rs – отправка видео
• send_audio_demo.rs – отправка аудио
• send_inline_keyboard_demo.rs – клавиатура
• callback_demo.rs – обработка нажатий кнопок
• forward_demo.rs – пересылка сообщения
• delete_messages_demo.rs – отправка и удаление
• ask_phone_demo.rs – запрос контакта
• ask_location_demo.rs – запрос геолокации

Запуск примера:

export MAXBOT_TOKEN="ваш_токен"
export CHAT_ID="123456789"
cargo run --example send_text_demo

✅ Что уже реализовано

• Базовая HTTP-обёртка с rate limiting (30 RPS)
• Получение информации о боте (/me)
• Управление чатами: получение, обновление, удаление, выход
• Управление участниками и администраторами
• Отправка сообщений (текст, markdown, html, reply)
• Разбиение длинного текста на фрагменты (сохранение целостности слов/предложений)
• Отправка файлов (изображения, видео, аудио, документы)
• Пересылка сообщений
• Удаление сообщений (одиночное и массовое)
• Закрепление/открепление сообщений
• Действия бота (typing, upload_photo и т.д.)
• Long polling (/updates)
• Ответ на callback-запросы (inline-кнопки) – замена сообщения и уведомления
• Webhook-подписки (создание, удаление, список)
• Получение списка сообщений из чата (/messages с пагинацией)
• Редактирование сообщений (текст, клавиатура) – через answer_callback_query
• Удобные Builder'ы для параметров сообщений и клавиатур
• Поддержка всех типов вложений: стикеры, контакты, геолокация, share

🔮 Планы на будущее

• Получение информации о видео (/videos/{token})
• Автоматическая конвертация ответов в более удобные структуры
• Улучшенная обработка ошибок с конкретными типами
• Поддержка прокси
• Логирование через log или tracing
• Генерация документации с примерами на docs.rs

📄 Лицензия

Проект распространяется под лицензией MIT.

🤝 Вклад

Принимаются pull request'ы. Для крупных изменений сначала откройте issue для обсуждения.

🌐 Полезные ссылки

• Документация API MAX
• Репозиторий библиотеки
• Crates.io