MaxBotApi Ruby Client

Ruby client for the MAX Bot API, mirroring the official Go client.

Installation

gem install max_bot_api

Or in your Gemfile:

gem "max_bot_api"

Quick start

require "max_bot_api"

client = MaxBotApi::Client.new(token: ENV.fetch("TOKEN"))

me = client.bots.get_bot
puts "Bot: #{me[:name]}"

client.messages.send(
  MaxBotApi::Builders::MessageBuilder.new
    .set_chat(12345)
    .set_text("Hello from Ruby")
)

Features

  • Broad API coverage: Bots, Chats, Messages, Subscriptions, Uploads, Debugs.
  • Builder helpers for messages and keyboards.
  • Long polling updates with retry and backoff.
  • Webhook parsing and secret validation helpers.
  • Upload helpers for files, photos, audio, video.

Configuration

client = MaxBotApi::Client.new(
  token: ENV.fetch("TOKEN"),
  base_url: "https://platform-api.max.ru/",
  version: "1.2.5"
)

Notes:

  • The client uses Authorization: <token> (no Bearer).
  • Every request includes v=<version> query param.

Changelog

  • See CHANGELOG.md for version-by-version release notes.
  • See BREAKING_CHANGES_0.1.0_to_0.2.0.md for the detailed 0.2.0 migration notes.

Example:

message = MaxBotApi::Builders::MessageBuilder.new
  .set_chat(12345)
  .set_text("Hello")
  .add_photo_by_token("photo-token")

keyboard = MaxBotApi::Builders::KeyboardBuilder.new
row = keyboard.add_row
row.add_message("Continue")

message.add_keyboard(keyboard)
client.messages.send(message)

Common tasks

Send messages

message = MaxBotApi::Builders::MessageBuilder.new
  .set_chat(12345)
  .set_text("Hello, chat!")

client.messages.send(message)

Send with result

message = MaxBotApi::Builders::MessageBuilder.new
  .set_chat(12345)
  .set_text("Hello, chat!")

sent = client.messages.send_with_result(message)
puts sent[:body][:mid]

Reply to a message

message = MaxBotApi::Builders::MessageBuilder.new
  .set_chat(12345)
  .set_reply("Thanks!", "mid123")

client.messages.send(message)

Long polling updates

client.each_update do |update|
  case update[:update_type]
  when "message_created"
    text = update.dig(:message, :body, :text)
    puts "New message: #{text}"
  end
end

Webhook parsing

body = request.body.read
halt 401 unless client.webhook_secret_valid?(headers: request.env, secret: ENV.fetch("WEBHOOK_SECRET"))
update = client.parse_webhook(body)

message = MaxBotApi::Builders::MessageBuilder.new
  .set_chat(12345)
  .set_text("https://max.ru")
  .set_disable_link_preview(true)

client.messages.send(message)

Pin and unpin chat messages

client.chats.pin_message(chat_id: 12345, message_id: "mid123")
client.chats.get_pinned_message(chat_id: 12345)
client.chats.unpin_message(chat_id: 12345)

Builders

Keyboard

keyboard = client.messages.new_keyboard_builder
keyboard
  .add_row
  .add_geolocation("Share location", true)
  .add_contact("Share contact")

keyboard
  .add_row
  .add_link("Open MAX", "positive", "https://max.ru")
  .add_callback("Audio", "negative", "audio")

message = MaxBotApi::Builders::MessageBuilder.new
  .set_chat(12345)
  .add_keyboard(keyboard)
  .set_text("Choose an action")

client.messages.send(message)

Attachments

photo = client.uploads.upload_photo_from_file(path: "./image.png")

message = MaxBotApi::Builders::MessageBuilder.new
  .set_chat(12345)
  .add_photo(photo)

client.messages.send(message)

Error handling

begin
  client.bots.get_bot
rescue MaxBotApi::ApiError => e
  puts "API error: #{e.message}"
rescue MaxBotApi::TimeoutError => e
  puts "Timeout: #{e.message}"
end

More docs

  • docs/01-your-first-bot.md
  • docs/02-listen-and-respond.md
  • docs/03-attachments.md
  • docs/04-keyboard.md
  • docs/05-uploads.md
  • docs/06-subscriptions.md

Examples

See examples/ for ready-to-run scripts.