Project

max_bot_api

0.0
A long-lived project that still receives updates
max_bot_apicreogen/max_bot_apiHomepageDocumentationSource CodeBug Tracker
Ruby gem that mirrors the MAX Bot API Go client.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
274
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.2.0
Total releases
2
First release
1980-01-02
Latest release
2026-03-05
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-02-20
Reverse Dependencies
0

 Dependencies

Development

minitest
~> 6.0
webmock
~> 3.18

Runtime

base64
~> 0.1
faraday
~> 2.7
faraday-multipart
~> 1.0
 Project Readme

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

  • Full API coverage: Bots, Chats, Messages, Subscriptions, Uploads, Debugs.
  • Builder helpers for messages and keyboards.
  • Long polling updates with retry and backoff.
  • Webhook parsing helper.
  • 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.

0.2.0 updates

  • Default API host is now https://platform-api.max.ru/ (override with base_url: if you need the legacy host).
  • Message send/edit retries automatically when the API responds with attachment.not.ready.
  • New helpers: MessageBuilder#add_photo_by_token, KeyboardRowBuilder#add_message.

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
update = client.parse_webhook(body)

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.