Laravel Telegram Notifier Laravel Package

Getting Started

Install and wire it up

composer require usmonaliyev/laravel-telegram-notifier
php artisan vendor:publish --tag=telegram-notifier-config

Laravel 11+ users: the service provider is auto-discovered; no config/app.php edits.

Configure credentials

Add to .env:

TELEGRAM_BOT_TOKEN=123456:ABC...
TELEGRAM_CHAT_ID=-1001234567890

Get the token from @BotFather. The chat ID: message the bot, then hit https://api.telegram.org/bot<TOKEN>/getUpdates and read message.chat.id. Group chat IDs are negative — that trips up almost everyone on day one.

Where to look first

1. config/telegram-notifier.php — confirms which env keys are read, whether a queue connection or timeout is exposed.
2. The README's "Usage" section — this package is small (8 stars, 0 dependents), so the README is the API contract.
3. vendor/usmonaliyev/laravel-telegram-notifier/src/ — it's a small source tree; skim the Facade and the main service class to see exactly what methods exist.

First use case — send a test message

php artisan tinker
>>> TelegramNotifier::send('Deploy to staging complete');

If that lands in your chat, the package is working. From there, the highest-value first integration is exception reporting (see next section).

Implementation Patterns

Exception reporting (Laravel 11/12) — bootstrap/app.php:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (Throwable $e) {
        if ($e instanceof \App\Exceptions\CriticalException
            || app()->environment('production')) {
            try {
                TelegramNotifier::send(
                    "🚨 ".get_class($e).": ".$e->getMessage()
                    ."\n".$_SERVER['REQUEST_URI'] ?? ''
                );
            } catch (Throwable $inner) {
                // never let the notifier mask the original exception
            }
        }
    });
})

Laravel 10 and below: override report() in app/Exceptions/Handler.php with the same guard.

Dedicated service wrapper — the pattern that survives package swaps. Never call the facade from controllers:

final class OpsAlert
{
    public function send(string $message, string $level = 'info'): void
    {
        if (! config('services.telegram.enabled')) return;
        try {
            TelegramNotifier::send("[{$level}] {$message}");
        } catch (Throwable $e) {
            report($e);
        }
    }
}

The enabled flag is the single most useful addition you'll make — lets you silence alerts in local/CI without touching config.

Queued notifications — alerts inside request handlers add latency. Either dispatch a job:

dispatch(function () use ($message) {
    TelegramNotifier::send($message);
})->onQueue('alerts');

or, if the package exposes a queue connection in its config, use that. Check the config file; if there's no queue support, the job wrapper above is the workaround.

Scheduled daily digest — more useful than per-event alerts:

Schedule::call(fn () => TelegramNotifier::send(
    "Daily: {$orders} orders, {$errors} errors"
))->dailyAt('09:00');

Logging-channel integration — if the package registers a telegram log driver (check config/logging.php after publish), you can fan out:

Log::channel('stack')->error('Payment gateway down');
// where 'stack' includes 'telegram'

This is the cleanest integration if supported — you get levels, context, and stack fan-out for free.

Gotchas and Tips

• Bot must be an admin in the group. Chat ID alone isn't enough; the bot needs permission to post. Add it as admin, not just a member.
• Negative chat IDs. -100… is a supergroup; -… (shorter) is a legacy group. Copy it from getUpdates, do not type it.
• Rate limits. Telegram allows ~30 messages/sec globally and ~20/min per chat. A noisy error handler can get you 429'd — and the client timeout means your request handler hangs. Queue it, throttle it, or aggregate.
• 4096-character limit. Stack traces will exceed this. Truncate to ~3500 chars and include just the top frames.
• Markdown/HTML parsing. If the package supports parse_mode, user-supplied content with _, *, [ will break rendering. Either escape it or use plain text. Symptoms: 400 Bad Request: can't parse entities.
• Config cache. php artisan config:cache is required after .env changes in production. A stale TELEGRAM_BOT_TOKEN is the #1 "it works locally" cause.
• Silent failures. HTTP client errors from Telegram are often swallowed by small packages. Wrap the call in try/catch and report() the inner exception at minimum; otherwise you'll believe alerts are firing when they aren't.
• No built-in retry/backoff in most packages this size. If delivery matters, put it behind a queued job with $tries = 3 and backoff().
• Testability. If the facade is bound to a concrete class, use TelegramNotifier::swap($fake) (works with Laravel facades) or bind an interface in your service provider. Don't let the facade leak into feature tests.
• Version pinning. 8 stars, single maintainer, last release March 2025 — pin to ^1.0 (or whatever the current tag is) and keep a fallback path. The OpsAlert wrapper above means swapping to laravel-notification-channels/telegram or a raw Http::post is a one-file change.
• Extension points. Check the service container bindings — small packages often let you rebind the HTTP client or a formatter class. If not available, the wrapper pattern is your escape hatch.