Readme in different languages: EN · RU

maxoxide

🦀 An async Rust library for building bots on the Max messenger platform, inspired by teloxide.

Features

✅ Full coverage of the Max Bot REST API
✅ Long polling (dev & test) and Webhook via axum (production)
✅ Strongly-typed events (Update, Message, Callback, …)
✅ Dispatcher with fluent handler registration and filters
✅ Inline keyboards (all button types: callback, link, message, request_contact, request_geo_location)
✅ File uploads — multipart, correct token flow for video/audio
✅ Markdown / HTML message formatting
✅ Webhook secret verification (X-Max-Bot-Api-Secret)
✅ Tokio async throughout

Quick start

[dependencies]
maxoxide = "0.1"
tokio    = { version = "1", features = ["full"] }

# For webhook support (production):
# maxoxide = { version = "0.1", features = ["webhook"] }

use maxoxide::{Bot, Context, Dispatcher};
use maxoxide::types::Update;

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    let bot = Bot::from_env();     // reads MAX_BOT_TOKEN env var
    let mut dp = Dispatcher::new(bot);

    dp.on_command("/start", |ctx: Context| async move {
        if let Update::MessageCreated { message, .. } = &ctx.update {
            ctx.bot.send_markdown(message.chat_id(), "Hello! 👋").await?;
        }
        Ok(())
    });

    dp.on_message(|ctx: Context| async move {
        if let Update::MessageCreated { message, .. } = &ctx.update {
            let text = message.text().unwrap_or("(no text)").to_string();
            ctx.bot.send_text(message.chat_id(), text).await?;
        }
        Ok(())
    });

    dp.start_polling().await;
}

MAX_BOT_TOKEN=your_token cargo run --example echo_bot

API methods

Method	Description
`bot.get_me()`	Bot info
`bot.send_text(chat_id, text)`	Send plain text
`bot.send_markdown(chat_id, text)`	Send Markdown
`bot.send_message(chat_id, body)`	Send message with attachments / keyboard
`bot.edit_message(mid, body)`	Edit a message
`bot.delete_message(mid)`	Delete a message
`bot.answer_callback(body)`	Answer an inline button press
`bot.get_chat(chat_id)`	Chat info
`bot.get_chats(…)`	List all group chats
`bot.edit_chat(chat_id, body)`	Edit chat title / description
`bot.leave_chat(chat_id)`	Leave a chat
`bot.get_members(…)`	List members
`bot.add_members(…)`	Add members
`bot.remove_member(…)`	Remove a member
`bot.get_admins(chat_id)`	List admins
`bot.pin_message(…)`	Pin a message
`bot.unpin_message(…)`	Unpin
`bot.send_action(chat_id, "typing")`	Typing indicator
`bot.subscribe(body)`	Register a webhook
`bot.get_upload_url(type)`	Get upload URL
`bot.upload_file(type, path, name, mime)`	Full two-step file upload
`bot.upload_bytes(type, bytes, name, mime)`	Same, from bytes
`bot.set_my_commands(commands)`	Set bot commands

Dispatcher filters

dp.on_command("/start", handler);             // specific command
dp.on_message(handler);                       // any new message
dp.on_edited_message(handler);               // edited message
dp.on_callback(handler);                     // any callback button
dp.on_callback_payload("btn:ok", handler);   // specific payload
dp.on_bot_started(handler);                  // user starts bot
dp.on_filter(|u| { … }, handler);            // custom predicate
dp.on(handler);                              // every update

First matching handler wins. Register more specific filters before general ones.

Inline keyboard

use maxoxide::types::{Button, KeyboardPayload, NewMessageBody};

let keyboard = KeyboardPayload {
    buttons: vec![
        vec![
            Button::callback("Yes ✅", "answer:yes"),
            Button::callback("No ❌",  "answer:no"),
        ],
        vec![Button::link("🌐 Website", "https://max.ru")],
    ],
};

let body = NewMessageBody::text("Are you sure?").with_keyboard(keyboard);
bot.send_message(chat_id, body).await?;

File upload

Max uses a two-step upload flow. upload_file / upload_bytes handle it automatically:

use maxoxide::types::{NewAttachment, NewMessageBody, UploadType, UploadedToken};

let token = bot
    .upload_file(UploadType::Image, "./photo.jpg", "photo.jpg", "image/jpeg")
    .await?;

let body = NewMessageBody {
    text: Some("Here's the photo!".into()),
    attachments: Some(vec![NewAttachment::Image {
        payload: UploadedToken { token },
    }]),
    ..Default::default()
};
bot.send_message(chat_id, body).await?;

Note: type=photo was removed from the Max API. Always use UploadType::Image.

Webhook server (`features = ["webhook"]`)

use maxoxide::webhook::WebhookServer;
use maxoxide::types::SubscribeBody;

bot.subscribe(SubscribeBody {
    url: "https://your-domain.com/webhook".into(),
    update_types: None,
    version: None,
    secret: Some("my_secret_123".into()),
}).await?;

WebhookServer::new(dp)
    .secret("my_secret_123")
    .path("/webhook")
    .serve("0.0.0.0:8443")
    .await;

Max requires HTTPS on port 443 and does not support self-signed certificates.

Project layout

maxoxide/
├── Cargo.toml
├── src/
│   ├── lib.rs          — public API & re-exports
│   ├── bot.rs          — Bot + all HTTP methods
│   ├── uploader.rs     — two-step file upload helpers
│   ├── dispatcher.rs   — Dispatcher, Filter, Context
│   ├── errors.rs       — MaxError
│   ├── webhook.rs      — axum webhook server (feature = "webhook")
│   ├── tests.rs        — unit tests
│   └── types/
│       └── mod.rs      — all types (User, Chat, Message, Update, …)
└── examples/
    ├── echo_bot.rs
    ├── keyboard_bot.rs
    └── webhook_bot.rs  (feature = "webhook")

Running tests

cargo test

License

MIT

maxoxide 0.1.0