balazstanka / laravel-telegram-alerts

v1.0.0 2026-10-01 19:31 UTC

Requires

• php: ^8.3
• illuminate/support: ^12.0||^13.0

Requires (Dev)

• larastan/larastan: ^3.9
• laravel/agent-detector: ^2.0
• laravel/chisel: ^0.1
• laravel/pao: ^1.0
• laravel/pint: ^1.29
• laravel/prompts: ^0.3
• orchestra/testbench: ^10.0||^11.0
• pestphp/pest: ^4.6||^5.0
• pestphp/pest-plugin-laravel: ^4.1||^5.0
• pestphp/pest-plugin-type-coverage: ^4.0||^5.0
• phpstan/extension-installer: ^1.4

MIT

• Balazs Tanka

• notifications
• alerts
• monitoring
• laravel
• telegram
• telegram-bot
• laravel-package

Published on Packagist.org on 2026-10-01 19:41 UTC

README

Laravel Telegram Alerts

Send alerts to Telegram from your Laravel app.

_{Based on laravel/package-skeleton, thanks to the Laravel team!}

Installation

You can install the package via Composer:

composer require balazstanka/laravel-telegram-alerts

You may publish all of the package's resources at once:

php artisan vendor:publish --tag="laravel-telegram-alerts"

Or, you may publish each resource individually:

Publishing the Configuration File

php artisan vendor:publish --tag="laravel-telegram-alerts-config"

Add your bot token (from @BotFather) and the chat id to your .env:

TELEGRAM_ALERT_BOT_TOKEN=123456:ABC-your-token
TELEGRAM_ALERT_CHAT_ID=-1001234567890

Usage

use BalazsTanka\TelegramAlerts\Facades\TelegramAlerts;

TelegramAlerts::message("You have a new subscriber to the {$newsletter->name} newsletter!");

The message is sent by a queued job, so your app keeps working when Telegram is slow or down. The job retries server errors with a backoff, waits as long as Telegram asks when it is rate limited, and fails right away on errors that a retry cannot fix (for example an unknown chat or a blocked bot). A failed delivery is logged.

Sending without the queue

Some alerts must arrive even when the queue itself is broken, for example a queue health check. sync() sends the message immediately and retries a few times:

TelegramAlerts::sync()->message('The queue worker is not running!');

Multiple chats

Add named chats to the chats array of the config file, then pick one with to(). You may also pass a chat id or a @channelusername:

TelegramAlerts::to('ops')->message('Disk is almost full');
TelegramAlerts::to(-1001234567890)->message('Hello');

Formatting

Messages are sent as plain text by default. Use html() or markdown() (MarkdownV2) to format them, and escape() for any text you don't control:

TelegramAlerts::html()->message('<b>Payment failed</b>: '.TelegramAlerts::escape($exception->getMessage()));

If Telegram cannot parse the formatting, the message is sent again as plain text, so the alert is not lost.

More options

TelegramAlerts::to('ops')
    ->silent()           // no notification sound
    ->inThread(42)       // a topic in a forum group
    ->delayMinutes(5)    // also: delayHours()
    ->message('Nightly backup finished');

Errors

An empty message, an unknown chat or a missing token throws a TelegramException, so you notice it during development. In production these are logged instead, and the request keeps working.

Set TELEGRAM_ALERT_ENABLED=false to turn alerts off, for example in CI.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Laravel Telegram Alerts! Please review our contributing guide to get started.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Balazs Tanka

License

Laravel Telegram Alerts is open-sourced software licensed under the MIT license.