max_bot_api 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3513bab6b7e83202a50274c5eba30655b5825bc56a5a6e26de78eae549e0e38f
-  data.tar.gz: 0f97c303649e2c8db1d54f64af70fffc99a030ab95866d089094cff533a4e98c
+  metadata.gz: 97114d1ff6c7d35facca9459c0543540867c2d48c6235dd6bb204e47c31a75b3
+  data.tar.gz: e7dec618f4d73dae79c33e692478c9dc5c8b06fcc0d3f14949c1178083d15aa3
 SHA512:
-  metadata.gz: 0d9ee73288cf706f2ba868e82bab3456bc6f7857d8b1a46cc8cf6fa273d2d0d4e800c93f62bce64f6bb822231385c4166d160fb6c13300649a1dcd18cf80a217
-  data.tar.gz: e4f90c9ccbc8ddaf116922c1dc3f6b7c83e4d261e20237e83b3d593703fd709898aa2ae201bfced427279c3b3378c318635e0fcbdf2c0b9721448f25a51962ed
+  metadata.gz: 8fec44603bf0f56f43e865097608bc786a3549ffa6a754d87803eeb0ada8f6851a074d44469c1e9f9e8629d342af908d252d30e0c576a8d701649af7ffdb2022
+  data.tar.gz: 7ac3fe1abc5125e7e63d610506ddf100c77b47c40c5bfe5c50ead48eea04b14cd79fc8f2a86e8073ee82eaa8f85212fcf30b2adea1a8fdbdfd56a9ff9694a99c

data/README.md

@@ -33,10 +33,10 @@ client.messages.send(
 
 ## Features
 
-- Full API coverage: Bots, Chats, Messages, Subscriptions, Uploads, Debugs.
+- Broad API coverage: Bots, Chats, Messages, Subscriptions, Uploads, Debugs.
 - Builder helpers for messages and keyboards.
 - Long polling updates with retry and backoff.
-- Webhook parsing helper.
+- Webhook parsing and secret validation helpers.
 - Upload helpers for files, photos, audio, video.
 
 ## Configuration
@@ -44,7 +44,7 @@ client.messages.send(
 ```ruby
 client = MaxBotApi::Client.new(
   token: ENV.fetch("TOKEN"),
-  base_url: "https://botapi.max.ru/",
+  base_url: "https://platform-api.max.ru/",
   version: "1.2.5"
 )
 ```
@@ -54,6 +54,27 @@ 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:
+
+```ruby
+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
@@ -103,9 +124,29 @@ end
 
 ```ruby
 body = request.body.read
+halt 401 unless client.webhook_secret_valid?(headers: request.env, secret: ENV.fetch("WEBHOOK_SECRET"))
 update = client.parse_webhook(body)
 ```
 
+### Disable link previews
+
+```ruby
+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
+
+```ruby
+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

data/docs/01-your-first-bot.md

@@ -38,7 +38,9 @@ client.messages.send(message)
 ```ruby
 client = MaxBotApi::Client.new(
   token: ENV.fetch("TOKEN"),
-  base_url: "https://botapi.max.ru/",
+  base_url: "https://platform-api.max.ru/",
   version: "1.2.5"
 )
 ```
+
+Note: if you still use the legacy host, set `base_url: "https://botapi.max.ru/"`.

data/docs/02-listen-and-respond.md

@@ -35,6 +35,7 @@ end
 
 ```ruby
 post "/webhook" do
+  halt 401 unless client.webhook_secret_valid?(headers: request.env, secret: ENV.fetch("WEBHOOK_SECRET"))
   update = client.parse_webhook(request.body.read)
 
   case update[:update_type]

data/docs/03-attachments.md

@@ -47,3 +47,13 @@ message = MaxBotApi::Builders::MessageBuilder.new
 
 client.messages.send(message)
 ```
+
+You can also attach a photo directly by token:
+
+```ruby
+message = MaxBotApi::Builders::MessageBuilder.new
+  .set_chat(12345)
+  .add_photo_by_token("photo-token")
+
+client.messages.send(message)
+```

data/docs/04-keyboard.md

@@ -18,6 +18,11 @@ keyboard
 keyboard
   .add_row
   .add_callback("Picture", "positive", "picture")
+  .add_message("Continue")
+
+keyboard
+  .add_row
+  .add_clipboard("Copy docs", "https://dev.max.ru/docs-api/methods/POST/messages")
 
 message = MaxBotApi::Builders::MessageBuilder.new
   .set_chat(12345)
@@ -34,3 +39,5 @@ client.messages.send(message)
 - `add_contact(text)`
 - `add_geolocation(text, quick)`
 - `add_open_app(text, app, payload, contact_id)`
+- `add_message(text)`
+- `add_clipboard(text, payload)`

data/docs/06-subscriptions.md

@@ -14,6 +14,8 @@ client.subscriptions.subscribe(
 )
 ```
 
+When handling webhook requests, validate the `X-Max-Bot-Api-Secret` header before parsing the body.
+
 ## Unsubscribe
 
 ```ruby

data/docs/api/methods.md

@@ -0,0 +1,59 @@
+# Методы API
+
+Источник: https://dev.max.ru/docs-api
+
+Клиент: MaxBotApi Ruby (`lib/max_bot_api/`).
+
+## bots
+
+| Метод | Путь | Описание | Клиент |
+| --- | --- | --- | --- |
+| `GET` | `/me` | Получение информации о боте | да |
+
+## chats
+
+| Метод | Путь | Описание | Клиент |
+| --- | --- | --- | --- |
+| `GET` | `/chats` | Получение списка всех групповых чатов | да |
+| `DELETE` | `/chats/{chatId}` | Удаление группового чата | нет |
+| `GET` | `/chats/{chatId}` | Получение информации о групповом чате | да |
+| `PATCH` | `/chats/{chatId}` | Изменение информации о групповом чате | да |
+| `POST` | `/chats/{chatId}/actions` | Отправка действия бота в групповой чат | да |
+| `DELETE` | `/chats/{chatId}/members` | Удаление участника из группового чата | частично (нет block) |
+| `GET` | `/chats/{chatId}/members` | Получение участников группового чата | да |
+| `POST` | `/chats/{chatId}/members` | Добавление участников в групповой чат | да |
+| `GET` | `/chats/{chatId}/members/admins` | Получение списка администраторов группового чата | да |
+| `POST` | `/chats/{chatId}/members/admins` | Назначить администратора группового чата | нет |
+| `DELETE` | `/chats/{chatId}/members/admins/{userId}` | Отменить права администратора в групповом чате | нет |
+| `DELETE` | `/chats/{chatId}/members/me` | Удаление бота из группового чата | да |
+| `GET` | `/chats/{chatId}/members/me` | Получение информации о членстве бота в групповом чате | да |
+| `DELETE` | `/chats/{chatId}/pin` | Удаление закреплённого сообщения в групповом чате | да |
+| `GET` | `/chats/{chatId}/pin` | Получение закреплённого сообщения в групповом чате | да |
+| `PUT` | `/chats/{chatId}/pin` | Закрепление сообщения в групповом чате | да |
+
+## subscriptions
+
+| Метод | Путь | Описание | Клиент |
+| --- | --- | --- | --- |
+| `DELETE` | `/subscriptions` | Отписка от обновлений | да |
+| `GET` | `/subscriptions` | Получение подписок | да |
+| `POST` | `/subscriptions` | Подписка на обновления | да (есть version) |
+| `GET` | `/updates` | Получение обновлений | да |
+
+## upload
+
+| Метод | Путь | Описание | Клиент |
+| --- | --- | --- | --- |
+| `POST` | `/uploads` | Загрузка файлов | да |
+
+## messages
+
+| Метод | Путь | Описание | Клиент |
+| --- | --- | --- | --- |
+| `POST` | `/answers` | Ответ на callback | да |
+| `DELETE` | `/messages` | Удалить сообщение | да |
+| `GET` | `/messages` | Получение сообщений | да |
+| `POST` | `/messages` | Отправить сообщение | да |
+| `PUT` | `/messages` | � едактировать сообщение | да |
+| `GET` | `/messages/{messageId}` | Получить сообщение | да |
+| `GET` | `/videos/{videoToken}` | Получить информацио о видео | нет |

data/docs/api/objects.md

@@ -0,0 +1,134 @@
+# Объекты API
+
+Источник: https://dev.max.ru/docs-api
+
+Всего объектов: 126
+
+| Объект | Краткое описание |
+| --- | --- |
+| `ActionRequestBody` |  |
+| `Attachment` | Общая схема, представляющая вложение сообщения |
+| `AttachmentPayload` |  |
+| `AttachmentRequest` | Запрос на прикрепление данных к сообщению |
+| `AudioAttachment` |  |
+| `AudioAttachmentRequest` | Запрос на прикрепление аудио к сообщению. ДОЛЖЕН быть единственным вложением в сообщении |
+| `BotAddedToChatUpdate` | Вы получите этот update, как только бот будет добавлен в чат |
+| `BotCommand` | до 32 элементов<br/>Команды, поддерживаемые ботом |
+| `BotInfo` | Объект включает общую информацию о боте, URL аватара и описание. Дополнительно содержит список команд, поддерживаемых… |
+| `BotPatch` |  |
+| `BotRemovedFromChatUpdate` | Вы получите этот update, как только бот будет удалён из чата |
+| `BotStartedUpdate` | Бот получает этот тип обновления, как только пользователь нажал кнопку `Start` |
+| `BotStoppedUpdate` | Бот получает этот тип обновления, как только пользователь останавливает бота |
+| `Button` |  |
+| `Callback` | Объект, отправленный боту, когда пользователь нажимает кнопку |
+| `CallbackAnswer` | Отправьте этот объект, когда ваш бот хочет отреагировать на нажатие кнопки |
+| `CallbackButton` | После нажатия на такую кнопку клиент отправляет на сервер полезную нагрузку, которая содержит |
+| `Chat` |  |
+| `ChatAdmin` |  |
+| `ChatAdminPermission` | Права администратора чата |
+| `ChatAdminsList` |  |
+| `ChatButton` | Кнопка, которая создает новый чат, как только первый пользователь на нее нажмёт. Бот будет добавлен в участники чата… |
+| `ChatList` |  |
+| `ChatMember` | Объект включает общую информацию о пользователе или боте, URL аватара и описание (при наличии). Дополнительно содержит… |
+| `ChatMembersList` |  |
+| `ChatPatch` |  |
+| `ChatStatus` | Статус чата для текущего бота |
+| `ChatTitleChangedUpdate` | Бот получит это обновление, когда будет изменено название чата |
+| `ChatType` | Тип чата: диалог, чат |
+| `ContactAttachment` |  |
+| `ContactAttachmentPayload` |  |
+| `ContactAttachmentRequest` | Запрос на прикрепление карточки контакта к сообщению. ДОЛЖЕН быть единственным вложением в сообщении |
+| `ContactAttachmentRequestPayload` |  |
+| `DataAttachment` | Attachment contains payload sent through `SendMessageButton` |
+| `DialogClearedUpdate` | Бот получает этот тип обновления сразу после очистки истории диалога. |
+| `DialogMutedUpdate` | Вы получите этот update, когда пользователь заглушит диалог с ботом |
+| `DialogRemovedUpdate` | Вы получите этот update, когда пользователь удаляет чат |
+| `DialogUnmutedUpdate` | Вы получите этот update, когда пользователь включит уведомления в диалоге с ботом |
+| `EmphasizedMarkup` | Представляет *курсив* |
+| `Error` | Сервер возвращает это, если возникло исключение при вашем запросе |
+| `FailedUserDetails` | Подробное описание, почему пользователь не был добавлен в чат |
+| `FileAttachment` |  |
+| `FileAttachmentPayload` |  |
+| `FileAttachmentRequest` | Запрос на прикрепление файла к сообщению. ДОЛЖЕН быть единственным вложением в сообщении |
+| `GetPinnedMessageResult` |  |
+| `GetSubscriptionsResult` | Список всех WebHook подписок |
+| `HeadingMarkup` | Представляет заголовок текста |
+| `HighlightedMarkup` | Представляет выделенную часть текста |
+| `Image` | Общая схема, описывающая объект изображения |
+| `InlineKeyboardAttachment` | Кнопки в сообщении |
+| `InlineKeyboardAttachmentRequest` | Запрос на прикрепление клавиатуры к сообщению |
+| `InlineKeyboardAttachmentRequestPayload` |  |
+| `Intent` | Намерение кнопки |
+| `Keyboard` | Клавиатура - это двумерный массив кнопок |
+| `LinkButton` | После нажатия на такую кнопку пользователь переходит по ссылке, которую она содержит |
+| `LinkMarkup` | Представляет ссылку в тексте |
+| `LinkedMessage` |  |
+| `LocationAttachment` |  |
+| `LocationAttachmentRequest` | Запрос на прикрепление клавиатуры к сообщению |
+| `MarkupElement` |  |
+| `MediaAttachmentPayload` |  |
+| `Message` | Сообщение в чате |
+| `MessageBody` | Схема, представляющая тело сообщения |
+| `MessageButton` | Кнопка для запуска мини-приложения |
+| `MessageCallbackUpdate` | Вы получите этот `update` как только пользователь нажмёт кнопку |
+| `MessageChatCreatedUpdate` | Бот получит это обновление, когда чат будет создан, как только первый пользователь нажмёт кнопку чата |
+| `MessageCreatedUpdate` | ы получите этот `update`, как только сообщение будет создано |
+| `MessageEditedUpdate` | Вы получите этот `update`, как только сообщение будет отредактировано |
+| `MessageLinkType` | Тип связанного сообщения |
+| `MessageList` | Пагинированный список сообщений |
+| `MessageRemovedUpdate` | Вы получите этот `update`, как только сообщение будет удалено |
+| `MessageStat` | Статистика сообщения |
+| `ModifyMembersResult` | � езультат запроса на изменение списка участников |
+| `MonospacedMarkup` | Представляет `моноширинный` или блок ```код``` в тексте |
+| `NewMessageBody` |  |
+| `NewMessageLink` |  |
+| `OpenAppButton` | Кнопка для запуска мини-приложения |
+| `PhotoAttachment` | Вложение изображения |
+| `PhotoAttachmentPayload` |  |
+| `PhotoAttachmentRequest` |  |
+| `PhotoAttachmentRequestPayload` | Запрос на прикрепление изображения (все поля являются взаимоисключающими) |
+| `PhotoToken` |  |
+| `PhotoTokens` | Это информация, которую вы получите, как только изображение будет загружено |
+| `PinMessageBody` |  |
+| `Recipient` | Новый получатель сообщения. Может быть пользователем или чатом |
+| `ReplyButton` | After pressing this type of button client will send a message on behalf of user with given payload |
+| `ReplyKeyboardAttachment` | Custom reply keyboard in message |
+| `ReplyKeyboardAttachmentRequest` | Request to attach reply keyboard to message |
+| `RequestContactButton` | AПосле нажатия на такую кнопку клиент отправляет новое сообщение с вложением текущего контакта пользователя |
+| `RequestGeoLocationButton` | После нажатия на такую кнопку клиент отправляет новое сообщение с вложением текущего географического положения… |
+| `SendContactButton` | AПосле нажатия на такую кнопку клиент отправляет новое сообщение с вложением текущего контакта пользователя |
+| `SendGeoLocationButton` | После нажатия на такую кнопку клиент отправляет новое сообщение с вложением текущего географического положения… |
+| `SendMessageButton` | After pressing this type of button client will send a message on behalf of user with given payload |
+| `SendMessageResult` |  |
+| `SenderAction` | Действие, отправляемое участникам чата. Возможные значения: - `"typing_on"` — Бот набирает сообщение. -… |
+| `ShareAttachment` |  |
+| `ShareAttachmentPayload` | Полезная нагрузка запроса ShareAttachmentRequest |
+| `ShareAttachmentRequest` | Запрос на прикрепление предпросмотра медиафайла по внешнему URL |
+| `SimpleQueryResult` | Простой ответ на запрос |
+| `StickerAttachment` |  |
+| `StickerAttachmentPayload` |  |
+| `StickerAttachmentRequest` | Запрос на прикрепление стикера. ДОЛЖЕН быть единственным вложением в сообщении |
+| `StickerAttachmentRequestPayload` |  |
+| `StrikethroughMarkup` | Представляет ~зачекрнутый~ текст |
+| `StrongMarkup` | Представляет **жирный** текст |
+| `Subscription` | Схема для описания подписки на WebHook |
+| `SubscriptionRequestBody` | Запрос на настройку подписки WebHook |
+| `TextFormat` | Формат текста сообщения |
+| `UnderlineMarkup` | Представляет <ins>подчеркнутый</ins> текст |
+| `Update` | Объект`Update` представляет различные типы событий, произошедших в чате. См. его наследников > Чтобы получать события… |
+| `UpdateList` | Список всех обновлений в чатах, в которых ваш бот участвовал |
+| `UploadEndpoint` | Точка доступа, куда следует загружать ваши бинарные файлы |
+| `UploadType` | Тип загружаемого файла Поддерживаемые форматы: - `image`: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC - `video`: MP4, MOV,… |
+| `UploadedInfo` | Это информация, которую вы получите, как только аудио/видео будет загружено |
+| `User` | Объект, описывающий один из вариантов наследования: - [`User`](/docs-api/objects/User) — объект содержит общую… |
+| `UserAddedToChatUpdate` | Вы получите это обновление, когда пользователь будет добавлен в чат, где бот является администратором |
+| `UserIdsList` |  |
+| `UserMentionMarkup` | Представляет упоминание пользователя в тексте. Упоминание может быть как по имени пользователя, так и по ID, если у… |
+| `UserRemovedFromChatUpdate` | Вы получите это обновление, когда пользователь будет удалён из чата, где бот является администратором |
+| `UserWithPhoto` | Объект с общей информацией о пользователе или боте, дополнительно содержит URL аватара и описание |
+| `VideoAttachment` |  |
+| `VideoAttachmentDetails` |  |
+| `VideoAttachmentRequest` | Запрос на прикрепление видео к сообщению |
+| `VideoThumbnail` |  |
+| `VideoUrls` |  |
+| `bigint` |  |

data/docs/api/overview.md

@@ -0,0 +1,73 @@
+# Обзор API MAX
+
+Источник: https://dev.max.ru/docs-api
+
+## Что такое API MAX
+
+API MAX — это интерфейс для взаимодействия ботов с платформой через HTTPS-запросы к `platform-api.max.ru`. Он позволяет получать данные и выполнять действия (получение, создание, редактирование, удаление ресурсов).
+
+## HTTP методы
+
+- `GET` — получить ресурсы
+- `POST` — создать ресурсы (например, отправить сообщения)
+- `PUT` — редактировать ресурсы
+- `DELETE` — удалить ресурсы
+- `PATCH` — исправить ресурсы
+
+Параметры передаются в пути, query-строке или теле запроса.
+
+## Авторизация
+
+Передавайте токен в заголовке:
+
+```
+Authorization: <token>
+```
+
+Передача токена через query-параметры не поддерживается.
+
+## Ответы и коды ошибок
+
+Сервер возвращает JSON и HTTP-код:
+
+- `200` — успешная операция
+- `400` — недействительный запрос
+- `401` — ошибка аутентификации
+- `404` — ресурс не найден
+- `405` — метод не допускается
+- `429` — превышено количество запросов
+- `503` — сервис недоступен
+
+## Рекомендации по получению обновлений
+
+- Long Polling — для разработки и тестирования
+- Webhook — для production-окружения
+
+Ограничение по нагрузке: до **30 rps** на `platform-api.max.ru`.
+
+## Клавиатуры
+
+Поддерживаются inline-клавиатуры с ограничениями:
+
+- до `210` кнопок
+- до `30` рядов
+- до `7` кнопок в ряду (до `3` для кнопок `link`, `open_app`, `request_geo_location`, `request_contact`)
+- для `link` максимальный размер ссылки — `2048` символов
+
+Основные типы кнопок:
+
+- `callback` — событие `message_callback`
+- `link` — ссылка
+- `request_contact` — запрос контакта
+- `request_geo_location` — запрос геолокации
+- `open_app` — открытие мини-приложения
+- `message` — отправка текста
+
+## Форматирование текста
+
+Поддерживаются `markdown` и `html` в поле `format` объекта `NewMessageBody`.
+
+- Markdown: `*курсив*`, `**жирный**`, `~~зачерк~~`, `++подчерк++`, `` `code` ``
+- HTML: `<i>`, `<b>`, `<del>`, `<ins>`, `<pre>/<code>`, `<a href="...">`
+
+Для упоминаний используйте `max://user/user_id` и полное имя пользователя.

data/examples/attachments.rb

@@ -5,11 +5,17 @@ require 'max_bot_api'
 client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
 chat_id = ENV.fetch('CHAT_ID').to_i
 
-photo = client.uploads.upload_photo_from_file(path: './image.png')
+photo_token = ENV['PHOTO_TOKEN']
 
 message = MaxBotApi::Builders::MessageBuilder.new
                                              .set_chat(chat_id)
-                                             .add_photo(photo)
                                              .set_text('Photo attached')
 
+if photo_token && !photo_token.empty?
+  message.add_photo_by_token(photo_token)
+else
+  photo = client.uploads.upload_photo_from_file(path: './image.png')
+  message.add_photo(photo)
+end
+
 client.messages.send(message)

data/examples/keyboard.rb

@@ -15,6 +15,11 @@ keyboard
   .add_row
   .add_link('Open MAX', 'positive', 'https://max.ru')
   .add_callback('Audio', 'negative', 'audio')
+  .add_message('Continue')
+
+keyboard
+  .add_row
+  .add_clipboard('Copy docs', 'https://dev.max.ru/docs-api/methods/POST/messages')
 
 message = MaxBotApi::Builders::MessageBuilder.new
                                              .set_chat(chat_id)

data/examples/webhook_rack.rb

@@ -8,6 +8,10 @@ client = MaxBotApi::Client.new(token: ENV.fetch('TOKEN'))
 app = lambda do |env|
   req = Rack::Request.new(env)
   if req.post? && req.path == '/webhook'
+    unless client.webhook_secret_valid?(headers: env, secret: ENV.fetch('WEBHOOK_SECRET'))
+      return [401, { 'Content-Type' => 'text/plain' }, ['secret not allowed']]
+    end
+
     update = client.parse_webhook(req.body.read)
 
     if update[:update_type] == 'message_created'

data/lib/max_bot_api/builders/keyboard_builder.rb

@@ -85,6 +85,25 @@ module MaxBotApi
         add_button(button)
       end
 
+      # Add a message button.
+      def add_message(text)
+        button = {
+          type: 'message',
+          text: text
+        }
+        add_button(button)
+      end
+
+      # Add a clipboard button.
+      def add_clipboard(text, payload)
+        button = {
+          type: 'clipboard',
+          text: text,
+          payload: payload
+        }
+        add_button(button)
+      end
+
       # Build row payload.
       def build
         @cols

data/lib/max_bot_api/builders/message_builder.rb

@@ -4,7 +4,10 @@ module MaxBotApi
   module Builders
     # Builder for message payloads.
     class MessageBuilder
-      attr_reader :user_id, :chat_id, :reset
+      FORMAT_HTML = 'html'
+      FORMAT_MARKDOWN = 'markdown'
+
+      attr_reader :user_id, :chat_id, :reset, :disable_link_preview
 
       # Create a builder from an existing hash payload.
       # @param hash [Hash]
@@ -16,6 +19,9 @@ module MaxBotApi
         builder.set_user(hash[:user_id] || hash['user_id']) if hash.key?(:user_id) || hash.key?('user_id')
         builder.set_chat(hash[:chat_id] || hash['chat_id']) if hash.key?(:chat_id) || hash.key?('chat_id')
         builder.set_reset(hash[:reset] || hash['reset']) if hash.key?(:reset) || hash.key?('reset')
+        if hash.key?(:disable_link_preview) || hash.key?('disable_link_preview')
+          builder.set_disable_link_preview(hash[:disable_link_preview] || hash['disable_link_preview'])
+        end
 
         payload = hash[:message] || hash['message'] || hash
         builder.apply_payload(payload)
@@ -27,6 +33,7 @@ module MaxBotApi
         @user_id = nil
         @chat_id = nil
         @reset = false
+        @disable_link_preview = false
         @message = {
           attachments: []
         }
@@ -50,6 +57,12 @@ module MaxBotApi
         self
       end
 
+      # Toggle link previews in sent messages.
+      def set_disable_link_preview(disable_link_preview)
+        @disable_link_preview = !!disable_link_preview
+        self
+      end
+
       # Set message text.
       def set_text(text)
         @message[:text] = text
@@ -106,6 +119,11 @@ module MaxBotApi
         add_attachment(type: 'image', payload: { photos: payload[:photos] || payload['photos'] })
       end
 
+      # Attach a photo payload by token.
+      def add_photo_by_token(token)
+        add_attachment(type: 'image', payload: { token: token })
+      end
+
       # Attach audio payload.
       def add_audio(uploaded_info)
         add_attachment(type: 'audio', payload: uploaded_info)
@@ -169,6 +187,11 @@ module MaxBotApi
         @reset
       end
 
+      # Whether link previews are disabled for message delivery.
+      def disable_link_preview?
+        @disable_link_preview
+      end
+
       # Return the message payload hash.
       def to_h
         @message

data/lib/max_bot_api/client.rb

@@ -6,9 +6,11 @@ module MaxBotApi
   # Main API client. Holds auth config and provides resource accessors.
   class Client
     # Default API base URL.
-    DEFAULT_BASE_URL = 'https://botapi.max.ru/'
+    DEFAULT_BASE_URL = 'https://platform-api.max.ru/'
     # Default API version appended as query param.
     DEFAULT_VERSION = '1.2.5'
+    # Webhook secret header name.
+    SECRET_HEADER = 'X-Max-Bot-Api-Secret'
     # Default pause between update polling loops.
     DEFAULT_PAUSE = 1
     # Default limit for updates requests.
@@ -131,6 +133,13 @@ module MaxBotApi
       Updates::Parser.parse_update(body.to_s, debug: debug)
     end
 
+    # Validates the webhook secret header against the expected secret.
+    # @param headers [Hash]
+    # @param secret [String]
+    def webhook_secret_valid?(headers:, secret:)
+      header_value(headers, SECRET_HEADER) == secret.to_s
+    end
+
     # Perform an HTTP request.
     # @param method [Symbol]
     # @param path [String]
@@ -192,11 +201,23 @@ module MaxBotApi
       body.values.any? { |value| value.is_a?(Faraday::Multipart::FilePart) }
     end
 
+    def header_value(headers, name)
+      target = name.to_s.downcase
+
+      headers.each do |key, value|
+        normalized = key.to_s.downcase.tr('_', '-')
+        normalized = normalized.sub(/\Ahttp-/, '')
+        return value if normalized == target
+      end
+
+      nil
+    end
+
     def handle_response(response)
       return parse_body(response) if response.status == 200
 
-      api_message = parse_error_message(response)
-      raise ApiError.new(code: response.status, message: api_message)
+      error_payload = parse_error_payload(response)
+      raise ApiError.new(code: response.status, message: error_payload[:message], details: error_payload[:details])
     end
 
     def parse_body(response)
@@ -209,17 +230,20 @@ module MaxBotApi
       JSON.parse(body, symbolize_names: true)
     end
 
-    def parse_error_message(response)
+    def parse_error_payload(response)
       body = response.body.to_s
-      return response.reason_phrase.to_s if body.empty?
+      return { message: response.reason_phrase.to_s, details: nil } if body.empty?
 
       json = JSON.parse(body)
-      return json['error'] if json.is_a?(Hash) && json['error']
-      return json['message'] if json.is_a?(Hash) && json['message']
+      if json.is_a?(Hash)
+        return { message: json['code'], details: json['message'] } if json['code'] && json['message']
+        return { message: json['error'], details: json['details'] || json['message'] } if json['error']
+        return { message: json['message'], details: json['details'] } if json['message']
+      end
 
-      response.reason_phrase.to_s
+      { message: response.reason_phrase.to_s, details: nil }
     rescue JSON::ParserError
-      response.reason_phrase.to_s
+      { message: response.reason_phrase.to_s, details: nil }
     end
   end
 end

data/lib/max_bot_api/errors.rb

@@ -27,6 +27,10 @@ module MaxBotApi
       other.is_a?(ApiError) && other.code == code
     end
 
+    def attachment_not_ready?
+      message == 'attachment.not.ready'
+    end
+
     private
 
     def build_message

data/lib/max_bot_api/resources/chats.rb

@@ -86,6 +86,25 @@ module MaxBotApi
       def send_action(chat_id:, action:)
         @client.request(:post, "chats/#{chat_id}/actions", body: { action: action })
       end
+
+      # Pin a message in chat.
+      # @param chat_id [Integer]
+      # @param message_id [String]
+      def pin_message(chat_id:, message_id:)
+        @client.request(:put, "chats/#{chat_id}/pin", body: { message_id: message_id })
+      end
+
+      # Fetch the currently pinned message.
+      # @param chat_id [Integer]
+      def get_pinned_message(chat_id:)
+        @client.request(:get, "chats/#{chat_id}/pin")
+      end
+
+      # Remove the currently pinned message.
+      # @param chat_id [Integer]
+      def unpin_message(chat_id:)
+        @client.request(:delete, "chats/#{chat_id}/pin")
+      end
     end
   end
 end

data/lib/max_bot_api/resources/messages.rb

@@ -14,9 +14,11 @@ module MaxBotApi
       def get_messages(chat_id: nil, message_ids: nil, from: nil, to: nil, count: nil)
         query = {}
         query['chat_id'] = chat_id if chat_id && chat_id.to_i != 0
-        Array(message_ids).each do |mid|
-          query['message_ids'] ||= []
-          query['message_ids'] << mid
+        query['message_ids'] = Array(message_ids).join(',') if message_ids && !Array(message_ids).empty?
+        if from && to
+          from_i = from.to_i
+          to_i = to.to_i
+          from, to = to, from if from_i > to_i
         end
         query['from'] = from if from && from.to_i != 0
         query['to'] = to if to && to.to_i != 0
@@ -36,11 +38,13 @@ module MaxBotApi
       # @param message_id [String]
       # @param message [MaxBotApi::Builders::MessageBuilder, Hash]
       def edit_message(message_id:, message:)
-        body = message_payload(message)
-        result = @client.request(:put, 'messages', query: { 'message_id' => message_id }, body: body)
-        return true if result.is_a?(Hash) && result[:success]
+        with_attachment_retry do
+          body = message_payload(message)
+          result = @client.request(:put, 'messages', query: { 'message_id' => message_id }, body: body)
+          return true if result.is_a?(Hash) && result[:success]
 
-        raise Error, (result[:message] || 'message update failed')
+          raise Error, (result[:message] || 'message update failed')
+        end
       end
 
       # Delete a message by ID.
@@ -64,13 +68,13 @@ module MaxBotApi
       # Send a message builder without returning the created message.
       # @param message [MaxBotApi::Builders::MessageBuilder, Hash]
       def send(message)
-        send_message(message, with_result: false)
+        with_attachment_retry { send_message(message, with_result: false) }
       end
 
       # Send a message builder and return the created message hash.
       # @param message [MaxBotApi::Builders::MessageBuilder, Hash]
       def send_with_result(message)
-        send_message(message, with_result: true)
+        with_attachment_retry { send_message(message, with_result: true) }
       end
 
       # Check if a message can be sent to the provided phone numbers.
@@ -106,6 +110,7 @@ module MaxBotApi
         query = {}
         query['chat_id'] = message.chat_id if message.chat_id && message.chat_id.to_i != 0
         query['user_id'] = message.user_id if message.user_id && message.user_id.to_i != 0
+        query['disable_link_preview'] = 'true' if message.disable_link_preview?
 
         response = @client.request(:post, 'messages', query: query, body: message_payload(message),
                                                       reset: message.reset?)
@@ -133,6 +138,19 @@ module MaxBotApi
                      end
         end
       end
+
+      def with_attachment_retry
+        attempts = 0
+        begin
+          yield
+        rescue ApiError => e
+          attempts += 1
+          raise e unless e.attachment_not_ready? && attempts < Client::MAX_RETRIES
+
+          sleep(2**(attempts - 1))
+          retry
+        end
+      end
     end
   end
 end

data/lib/max_bot_api/resources/uploads.rb

@@ -32,8 +32,12 @@ module MaxBotApi
       # @param url [String]
       def upload_media_from_url(type:, url:)
         response = Faraday.get(url.to_s)
+        raise Error, "fetch URL failed: HTTP #{response.status}" unless response.status.between?(200, 299)
+
         name = attachment_name(response.headers)
         upload_media_from_reader_with_name(type: type, io: StringIO.new(response.body), name: name)
+      rescue Faraday::Error => e
+        raise NetworkError.new(op: 'GET upload source', original_error: e)
       end
 
       # Upload media from an IO object.
@@ -89,20 +93,48 @@ module MaxBotApi
         upload_type = UPLOAD_TYPES.fetch(type.to_sym) { type.to_s }
         endpoint = @client.request(:post, 'uploads', query: { 'type' => upload_type })
 
-        file_name = name.to_s.empty? ? 'file' : name.to_s
+        file_name = name.to_s.empty? ? 'file' : File.basename(name.to_s)
         file_part = Faraday::Multipart::FilePart.new(io, nil, file_name)
 
         response = Faraday.post(endpoint[:url]) do |req|
           req.body = { 'data' => file_part }
         end
 
-        raise Error, "upload failed: #{response.status}" unless response.status == 200
+        raise upload_api_error(response) unless response.status.between?(200, 299)
+
+        return { token: endpoint[:token] } if %w[audio video].include?(upload_type) && endpoint[:token]
 
         JSON.parse(response.body, symbolize_names: true)
       rescue Faraday::Error => e
         raise NetworkError.new(op: 'POST uploads', original_error: e)
       end
 
+      def upload_api_error(response)
+        body = response.body.to_s
+        return Error.new("upload failed: HTTP #{response.status}") if body.empty?
+
+        json = begin
+          JSON.parse(body)
+        rescue StandardError
+          nil
+        end
+        if json.is_a?(Hash)
+          if json['code'] && json['message']
+            return ApiError.new(code: response.status, message: json['code'], details: json['message'])
+          end
+
+          if json['error']
+            return ApiError.new(code: response.status, message: json['error'],
+                                details: json['details'] || json['message'])
+          end
+          if json['message']
+            return ApiError.new(code: response.status, message: json['message'], details: json['details'])
+          end
+        end
+
+        Error.new("upload failed: HTTP #{response.status}")
+      end
+
       def attachment_name(headers)
         disposition = headers['content-disposition'].to_s
         return '' if disposition.empty?

data/lib/max_bot_api/version.rb

@@ -2,5 +2,5 @@
 
 module MaxBotApi
   # Gem version.
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: max_bot_api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ChatGPT Codex
 - Dmitry Merkushin
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -94,6 +95,9 @@ files:
 - docs/04-keyboard.md
 - docs/05-uploads.md
 - docs/06-subscriptions.md
+- docs/api/methods.md
+- docs/api/objects.md
+- docs/api/overview.md
 - examples/attachments.rb
 - examples/basic_send.rb
 - examples/keyboard.rb
@@ -120,6 +124,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/creogen/max_bot_api
   source_code_uri: https://github.com/creogen/max_bot_api/tree/main
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -134,7 +139,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 3.4.10
+signing_key: 
 specification_version: 4
 summary: Ruby client for MAX Bot API
 test_files: []