RuMaxBot.ru теперь с кнопками
В современной веб-разработке интеграция с мессенджерами для отправки уведомлений, алертов или интерактивных сообщений стала стандартом. Если ваш проект работает на Laravel и вы используете шлюз rumaxbot.ru для работы с MAX Messenger, то пакет RuMaxBot (ww-site/rumaxbot) может стать отличным решением для быстрого, безопасного и чистого подключения этого функционала.
В этом обзоре мы разберем ключевые возможности пакета, процесс установки, примеры использования и новейшую функцию управления выбором пользователя.
Что такое RuMaxBot?
RuMaxBot – это Composer-пакет для Laravel (поддерживает актуальные версии, включая Laravel 12), который предоставляет удобный PHP-интерфейс для взаимодействия с API шлюза rumaxbot.ru. Он абстрагирует рутинные задачи: формирование HTTP-запросов, валидацию данных, проверку HMAC-подписей вебхуков и сохранение состояния сообщений в базе данных.
Ключевые возможности
- Отправка сообщений: Поддержка простого текста (Markdown/HTML) и сложных сообщений с интерактивными кнопками (inline keyboard).
- Управление выбором: Возможность не только предлагать действия, но и отменять предыдущий выбор пользователя через специальную кнопку, что критически важно для корректной работы форм и опросов.
- Двусторонняя связь (Webhooks): Встроенный механизм приема и валидации входящих вебхуков.
- Корреляция сообщений: Использование
external_message_id(UUID) для надежной связки отправленного сообщения и полученного ответа. - Готовый scaffolding: Команда
php artisan rumaxbot:installавтоматически создает миграции, модели, контроллеры и маршруты. - Чистая архитектура: Активное использование DTO, Enum-ов и фасадов.
Установка и настройка
Подключение выполняется стандартно:
composer require ww-site/rumaxbot php artisan vendor:publish --tag=rumaxbot-config
Не забудьте добавить учетные данные в .env:
RUMAXBOT_BASE_URL=https://rumaxbot.ru RUMAXBOT_API_TOKEN=mbk_your_api_key_here RUMAXBOT_WEBHOOK_SECRET=your_webhook_secret
Поток данных и корреляция
Главная особенность надежной интеграции – возможность понять, на какое именно сообщение ответил пользователь. RuMaxBot решает эту задачу через поле external_message_id:
- Ваше приложение генерирует UUID и сохраняет его в БД вместе с контекстом.
- При отправке сообщения этот UUID передается в API шлюза.
- Когда пользователь взаимодействует с сообщением, шлюз возвращает вебхук с этим же ID.
- Контроллер находит запись в БД и выполняет бизнес-логику.
Примеры использования
Отправка интерактивного сообщения с кнопками
use App\Models\RuMaxBotMessage;
use Illuminate\Support\Str;
use RuMaxBot\DataTransferObjects\InlineButton;
use RuMaxBot\DataTransferObjects\InlineKeyboardAttachment;
use RuMaxBot\DataTransferObjects\SendMessageData;
use RuMaxBot\Enums\MessageFormat;
use RuMaxBot\Facades\RuMaxBot;
$externalId = (string) Str::uuid();
// Сохраняем контекст в БД
$stored = RuMaxBotMessage::query()->create([
'external_message_id' => $externalId,
'text' => 'Выберите действие по заказу #123',
'format' => MessageFormat::Markdown,
'context' => ['order_id' => 123],
]);
// Отправляем сообщение
$response = RuMaxBot::send(new SendMessageData(
text: $stored->text,
format: MessageFormat::Markdown,
externalMessageId: $externalId,
attachments: [
InlineKeyboardAttachment::make([
[
InlineButton::callback('Принять', 'order:accept'),
InlineButton::callback('Отклонить', 'order:reject'),
],
[
// Новая возможность: кнопка отмены выбора
InlineButton::callback('Отменить выбор', 'order:cancel_selection'),
],
]),
],
));
$stored->forceFill(['rumaxbot_message_id' => $response->id])->save();
Обработка вебхука и отмена выбора
После выполнения команды php artisan rumaxbot:install в проекте появляется готовый RuMaxBotWebhookController. Он автоматически проверяет HMAC-подпись и находит сообщение в БД. Теперь вы можете легко обрабатывать сценарии отмены:
// Внутри контроллера вебхука
$payload = $webhookData['callback']['payload'];
if ($payload === 'order:cancel_selection') {
// Логика сброса состояния или удаления временных данных
// Например: $stored->update(['status' => 'cancelled']);
// Можно отправить новое сообщение с подтверждением отмены
RuMaxBot::send(new SendMessageData(
text: '✅ Ваш выбор отменен.',
externalMessageId: (string) Str::uuid(),
));
} elseif ($payload === 'order:accept') {
// Логика принятия заказа
}
💡 Важно: Кнопка «Отменить выбор» позволяет пользователю вернуться в исходное состояние, если он случайно нажал не ту кнопку или передумал. Это значительно улучшает UX при работе с ботами в MAX Messenger.
Тестирование и отладка
Для быстрой проверки подключения используйте Artisan-команду:
php artisan rumaxbot:test --message="Привет из Laravel!" --format=markdown
Пакет также покрыт unit- и feature-тестами (PHPUnit), что гарантирует стабильность работы.
Заключение
RuMaxBot – это зрелый инструмент для разработчиков на Laravel. Недавнее обновление, добавившее поддержку кнопки «Отменить выбор», делает его еще более гибким для создания сложных интерактивных сценариев. Пакет избавляет от написания «велосипедов», обеспечивает безопасность (HMAC) и поддерживает чистоту кода.
Если вы используете MAX Messenger в своих проектах, этот пакет заслуживает внимания.
🔗 Ссылка на репозиторий: github.com/ww-site/RuMaxBot
🔗 Новости и обновления: rumaxbot.ru/novoe
Комментарии 0