Skip to content

creogen/max_bot_api

Repository files navigation

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.

About

Ruby client for MAX Bot API

Resources

Stars

Watchers

Forks

Packages

 
 
 

Contributors