MAX Notification Channel for Laravel

Канал уведомлений Laravel для мессенджера MAX.

Установка

composer require alexwebprog/laravel-notification-channel-max

Опубликуйте конфиг:

php artisan vendor:publish --tag=max-notification-config

Добавьте токен бота в .env:

MAX_NOTIFICATION_BOT_TOKEN=your-bot-token

Настройка

URL API и сертификат Минцифры

По умолчанию пакет использует https://platform-api2.max.ru и встроенный сертификат удостоверяющего центра Минцифры для проверки SSL. Это работает «из коробки» без дополнительной настройки.

При необходимости вы можете переопределить настройки в .env:

Использование

Канал уведомлений

Добавьте метод toMax в ваш класс уведомления:

use NotificationChannels\Max\MaxChannel;
use NotificationChannels\Max\MaxMessage;

class InvoicePaid extends Notification
{
    public function via($notifiable): array
    {
        return [MaxChannel::class];
    }

    public function toMax($notifiable): MaxMessage
    {
        return MaxMessage::create('Ваш счёт оплачен!')
            ->markdown();
    }
}

В модели User (или другом Notifiable) добавьте метод маршрутизации:

public function routeNotificationForMax(): ?int
{
    return $this->max_user_id;
}

On-demand уведомления (Notification::route)

Можно отправлять уведомления без привязки к модели через Notification::route:

use Illuminate\Support\Facades\Notification;

// Отправка пользователю по user_id
Notification::route('max', $maxUserId)
    ->notify(new MyNotification($data));

// Отправка в чат/канал по chat_id
Notification::route('max', ['chat_id' => $chatId])
    ->notify(new MyNotification($data));

Скалярное значение трактуется как user_id. Для отправки в чат передайте массив ['chat_id' => $chatId].

Прямая отправка

Вы можете отправлять сообщения напрямую без уведомлений:

use NotificationChannels\Max\MaxMessage;

MaxMessage::create('Привет!')
    ->to($maxUserId)
    ->markdown()
    ->send();

Отправка в канал/чат:

MaxMessage::create('Новый пост в канале')
    ->toChat($chatId)
    ->send();

Использование другого токена бота

Вы можете переопределить токен бота для конкретного сообщения. Это полезно, если у вас несколько ботов:

MaxMessage::create('Сообщение от другого бота')
    ->to($maxUserId)
    ->token('токен-другого-бота')
    ->send();

В уведомлении:

public function toMax($notifiable): MaxMessage
{
    return MaxMessage::create('Уведомление от другого бота')
        ->token('токен-другого-бота');
}

При использовании ->token() все операции (отправка сообщения, загрузка файлов) будут выполняться с указанным токеном.

API

| Метод | Описание | |---|---| | create(?string $text) | Создать экземпляр сообщения (статический) | | text(string $text) | Задать текст сообщения | | to(int $userId) | Задать ID пользователя-получателя | | toChat(int $chatId) | Задать ID чата/канала | | token(string $token) | Использовать другой токен бота | | markdown() | Формат текста — Markdown | | html() | Формат текста — HTML | | format(string $format) | Задать формат текста явно | | disableLinkPreview(bool $disable = true) | Отключить превью ссылок | | silent(bool $silent = true) | Отправить без уведомления | | inlineKeyboard(array $buttons) | Добавить инлайн-клавиатуру | | photo(string $filePath) | Загрузить и прикрепить изображение | | video(string $filePath) | Загрузить и прикрепить видео | | audio(string $filePath) | Загрузить и прикрепить аудио | | file(string $filePath) | Загрузить и прикрепить файл | | attachment(array $attachment) | Добавить произвольное вложение | | replyTo(string $messageId) | Ответить на сообщение | | forward(string $messageId) | Переслать сообщение | | retryWhenNotReady(array $delays) | Задать паузы повтора при attachment.not.ready | | send() | Отправить сообщение напрямую | | edit(string $messageId) | Редактировать отправленное сообщение | | delete(string $messageId, ?string $token) | Удалить сообщение (статический) |

Медиафайлы

Пакет поддерживает загрузку и отправку медиафайлов:

// Изображение
MaxMessage::create('Фото')
    ->to($userId)
    ->photo('/path/to/image.jpg')
    ->send();

// Видео
MaxMessage::create('Видео')
    ->to($userId)
    ->video('/path/to/video.mp4')
    ->send();

// Аудио
MaxMessage::create('Аудио')
    ->to($userId)
    ->audio('/path/to/audio.mp3')
    ->send();

// Файл
MaxMessage::create('Документ')
    ->to($userId)
    ->file('/path/to/document.pdf')
    ->send();

После загрузки файла MAX может обрабатывать его асинхронно. Если при отправке API вернёт ошибку attachment.not.ready, метод send() автоматически повторит попытку с паузами (по умолчанию: 1, 1, 2, 2, 3, 3, 3 секунд, суммарно до ~15 секунд). Сам файл повторно не загружается — повторяется только отправка сообщения.

Вы можете задать свои паузы или отключить повторы:

// Свои паузы между попытками (в секундах)
MaxMessage::create('Фото')
    ->to($userId)
    ->photo('/path/to/image.jpg')
    ->retryWhenNotReady([2, 5, 10])
    ->send();

// Отключить автоматический повтор
MaxMessage::create('Фото')
    ->to($userId)
    ->photo('/path/to/image.jpg')
    ->retryWhenNotReady([])
    ->send();

Кнопки

MaxMessage::create('Выберите действие:')
    ->to($userId)
    ->inlineKeyboard([
        [
            ['type' => 'link', 'text' => 'Открыть сайт', 'url' => 'https://example.com'],
        ],
        [
            ['type' => 'callback', 'text' => 'Нажми меня', 'payload' => 'button_clicked'],
        ],
        [
            ['type' => 'request_contact', 'text' => 'Отправить контакт'],
        ],
    ])
    ->send();

Редактирование сообщений

// Редактировать текст сообщения
MaxMessage::create('Обновлённый текст')
    ->markdown()
    ->edit($messageId);

// Редактировать с заменой вложений
MaxMessage::create('Новый текст с фото')
    ->photo('/path/to/new-image.jpg')
    ->edit($messageId);

// Редактировать с указанием токена другого бота
MaxMessage::create('Обновлённый текст')
    ->token('токен-другого-бота')
    ->markdown()
    ->edit($messageId);

Сообщения с инлайн-кнопками можно редактировать без ограничений. Остальные сообщения в личных чатах — только в течение 7 дней. В групповых чатах и каналах ограничений нет. Лимит: не более 2 редактирований в секунду на один чат.

Удаление сообщений

use NotificationChannels\Max\MaxMessage;

// Удалить сообщение
MaxMessage::delete($messageId);

// Удалить с указанием токена другого бота
MaxMessage::delete($messageId, 'токен-другого-бота');

Бот может удалять свои сообщения в личных чатах и любые сообщения в групповых чатах/каналах (при наличии прав администратора). Лимит: не более 2 удалений в секунду на один чат.

Тихая отправка

MaxMessage::create('Тихое сообщение')
    ->to($userId)
    ->silent()
    ->send();

Миграция с v1.x

В версии 2.0 изменён URL API по умолчанию с platform-api.max.ru на platform-api2.max.ru и добавлена автоматическая поддержка сертификата Минцифры. Обновите конфигурацию:

php artisan vendor:publish --tag=max-notification-config --force

Лицензия

MIT