Laravel Telegram Logger

Send Laravel logs and exception alerts to a Telegram chat, group or forum topic through a regular Monolog channel.

• one bot, many channels: every log channel can point to its own chat and topic (message_thread_id)
• HTML or MarkdownV2 with correct escaping, Blade templates
• long messages are split at the 4096 limit without breaking markup
• throttling of identical errors, 429 retry_after handling, optional queue
• never throws and never blocks a request for longer than timeout
• php artisan telegram-logger:test to check the setup
• no dependencies besides illuminate/* and monolog/monolog

Laravel 10 and 11 are end-of-life. Composer refuses to install them by default because of unpatched security advisories; the package still works there.

Installation

composer require xden/laravel-telegram-logger

Add the bot token and chat id to .env:

TELEGRAM_LOGGER_BOT_TOKEN=123456789:AAH...
TELEGRAM_LOGGER_CHAT_ID=-1001234567890

Add a channel to config/logging.php:

'channels' => [
    // ...
    'telegram' => [
        'driver' => 'telegram',
        'level' => 'error',
    ],
],

Check it:

php artisan telegram-logger:test --channel=telegram

Optionally publish the config and the views:

php artisan vendor:publish --tag=telegram-logger-config
php artisan vendor:publish --tag=telegram-logger-views

Getting the token, chat_id and message_thread_id

1. Open @BotFather, send /newbot and copy the token.

2. Add the bot to your group (or send /start to it in a private chat). For forum topics the group must have Topics enabled.

3. Send any message in the chat / topic, then open https://api.telegram.org/bot<TOKEN>/getUpdates:

   • message.chat.id is the chat_id (supergroups start with -100);
   • message.message_thread_id is the topic id.

   If the list is empty, the bot has privacy mode on: mention the bot in the message or disable privacy via BotFather → /setprivacy.

4. Alternatively, copy the link of a message inside a topic: https://t.me/c/1234567890/12/345 means chat_id = -1001234567890 and thread_id = 12.

Configuring channels

Every option of config/telegram-logger.php can be overridden per channel, anything not set on the channel comes from the package config. Three equivalent styles are supported.

1. telegram driver (recommended)

'telegram' => [
    'driver' => 'telegram',
    'level' => 'error',
],

'telegram_payments' => [
    'driver' => 'telegram',
    'thread_id' => env('TELEGRAM_LOG_PAYMENTS_THREAD_ID'),
    'level' => 'warning',
],

'telegram_ops' => [
    'driver' => 'telegram',
    'token' => env('TELEGRAM_OPS_BOT_TOKEN'),
    'chat_id' => env('TELEGRAM_OPS_CHAT_ID'),
    'parse_mode' => 'MarkdownV2',
    'template' => 'telegram-logger::minimal',
    'throttle' => 300,
    'queue' => ['connection' => 'redis', 'queue' => 'alerts'],
    'level' => 'critical',
],

2. Monolog handler

'telegram_payments' => [
    'driver' => 'monolog',
    'handler' => Xden\TelegramLogger\TelegramHandler::class,
    'with' => [
        'token' => env('TELEGRAM_LOG_TOKEN'),
        'chatId' => env('TELEGRAM_LOG_CHAT_ID'),
        'threadId' => env('TELEGRAM_LOG_PAYMENTS_THREAD_ID'),
        'level' => 'warning',
        // optional: parseMode, throttle, queue, timeout, bubble,
        // and 'config' => [...] for any other option
    ],
],

3. custom driver (as in grkamil/laravel-telegram-logging)

'telegram' => [
    'driver' => 'custom',
    'via' => Xden\TelegramLogger\TelegramLoggerFactory::class,
    'chat_id' => env('TELEGRAM_COMPANY_CHAT_ID'),
    'level' => 'debug',
],

Usage

use Illuminate\Support\Facades\Log;

Log::channel('telegram_payments')->warning('Refund is stuck', ['order' => $order->id]);

Log::channel('telegram')->error('Import failed', ['exception' => $e]);

Or add the channel to the stack (LOG_STACK=single,telegram on Laravel 11+, 'channels' => ['single', 'telegram'] in the stack channel on Laravel 10).

Exceptions

Choose one of the options, otherwise every exception arrives twice.

A. Log stack. Laravel reports exceptions to the default channel, so adding telegram to the stack is enough:

LOG_CHANNEL=stack
LOG_STACK=single,telegram

B. Explicit report callback, when Telegram should get exceptions only (not every Log::error()), or a dedicated topic.

Laravel 11+, bootstrap/app.php:

use Illuminate\Support\Facades\Log;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (Throwable $e) {
        Log::channel('telegram')->error($e->getMessage(), ['exception' => $e]);
    });
})

Laravel 10, app/Exceptions/Handler.php:

public function register(): void
{
    $this->reportable(function (Throwable $e) {
        Log::channel('telegram')->error($e->getMessage(), ['exception' => $e]);
    });
}

Exceptions listed in $dontReport / dontReport() never reach any log channel. Use the ignore option to skip additional classes only for Telegram.

Options

config/telegram-logger.php, all of them can also be set on a channel:

Throttling

'throttle' => 300,

Identical events are sent at most once per 300 seconds. An event is identified by the exception class + file + line, or by level + message when there is no exception, and by the destination chat/topic. The cache is used through Cache::add(); if the cache is unavailable, throttling is skipped and the message is sent.

When Telegram answers 429 Too Many Requests, synchronous sending pauses for retry_after seconds.

Queue

TELEGRAM_LOGGER_QUEUE=true
TELEGRAM_LOGGER_QUEUE_CONNECTION=redis
TELEGRAM_LOGGER_QUEUE_NAME=alerts

or per channel 'queue' => ['connection' => 'redis', 'queue' => 'alerts'] (true uses the default connection, false forces synchronous sending for a channel).

Records are sent by Xden\TelegramLogger\Jobs\SendTelegramMessageJob. Its payload is encrypted because it contains the bot token. Network errors, 5xx and 429 are retried (up to 5 attempts, honouring retry_after). The job never throws, so a broken Telegram setup cannot create a failing job → log → job loop. If dispatching fails (e.g. Redis is down), the message is sent synchronously.

Templates

Built-in: telegram-logger::standard (header, message, exception, trace, request, context) and telegram-logger::minimal. Publish them with --tag=telegram-logger-views or point template to your own view.

Available variables: $fmt, $appName, $appEnv, $level, $levelName, $emoji, $message, $datetime, $exception (class, message, location, trace), $context, $extra, $request, $channel, $record.

Always print values through $fmt with {!! !!}. It escapes for the active parse mode, so one template works for HTML and MarkdownV2:

{!! $emoji !!} {!! $fmt->bold($appName) !!} {!! $fmt->code($levelName) !!}
{!! $fmt->text($message) !!}
@if ($exception)
{!! $fmt->pre($exception['class'].' '.$exception['location']) !!}
@endif

Helpers: text, bold, italic, code, pre($text, $language), link($text, $url). If a template fails to render, the built-in format is used and the error goes to error_log.

Manual alerts

use Xden\TelegramLogger\Facades\TelegramLog;

TelegramLog::send('Deploy finished');                      // default chat
TelegramLog::send('Payout batch is late', threadId: 12);   // a topic
TelegramLog::send('Nightly import OK', channel: 'telegram_ops', silent: true);
TelegramLog::send('<b>Raw</b> HTML', escape: false);       // your own markup

send() returns false instead of throwing. TelegramLog::escape($text) escapes text for the configured parse mode.

Test command

php artisan telegram-logger:test
php artisan telegram-logger:test --channel=telegram_payments --level=critical --message="Hello"

It prints the effective settings (the token is masked), sends a test record with a sample exception synchronously, bypassing queue and throttling, and explains Telegram errors.

Reliability

• The handler never throws. Its own failures (network, API errors, broken templates, missing config) are written to PHP's error_log, never to the Laravel log, so there is no recursion.
• A log call made while a message is being sent is ignored by the handler.
• All requests of one log record share the timeout budget; remaining parts are dropped when it runs out.
• Bot tokens are masked in every error message.

Troubleshooting

Nothing arrives and no error in the command? Check enabled, environments and the channel level, and look at the PHP error log ([telegram-logger] lines).

Migrating from grkamil/laravel-telegram-logging

TELEGRAM_LOGGER_BOT_TOKEN, TELEGRAM_LOGGER_CHAT_ID, TELEGRAM_LOGGER_MESSAGE_THREAD_ID, TELEGRAM_LOGGER_TIMEOUT, TELEGRAM_LOGGER_TEMPLATE, TELEGRAM_LOGGER_PROXY and TELEGRAM_LOGGER_API_HOST are read as they are. The template names laravel-telegram-logging::standard|minimal still resolve. Replace the channel:

// before
'telegram' => ['driver' => 'custom', 'via' => Logger\TelegramLogger::class, 'level' => 'debug'],
// after
'telegram' => ['driver' => 'telegram', 'level' => 'debug'],

Custom templates of the old package get $level_name, $appName, $appEnv, $datetime and $formatted, but should be rewritten with $fmt for proper escaping. Lumen is not supported.

Development

composer test      # PHPUnit
composer analyse   # PHPStan level 8 (Larastan)
composer format    # Pint

License

MIT, see LICENSE.