Notifications

Telegraph registers a Laravel notification channel named telegraph. It can be used to send application alerts, failed job notices, deployment updates, or selected log-related notifications to a Telegram chat.

Routing

Use Laravel's on-demand notifications when the target chat is known at send time:

use App\Notifications\ApplicationAlert;
use Illuminate\Support\Facades\Notification;

Notification::route('telegraph', [
    'bot_token' => env('TELEGRAPH_BOT_TOKEN'),
    'chat_id' => env('TELEGRAPH_ALERT_CHAT_ID'),
])->notify(new ApplicationAlert('Queue workers are failing'));

You may also return the route from your notifiable model:

use DefStudio\Telegraph\Models\TelegraphChat;

public function routeNotificationForTelegraph(): TelegraphChat|string|array
{
    return [
        'bot_token' => config('services.telegram.bot_token'),
        'chat_id' => $this->telegram_chat_id,
    ];
}

The route may be:

• a Telegram chat id
• a TelegraphChat model
• a TelegraphBot model
• an array with chat or chat_id, and optionally bot or bot_token

When only a chat id is provided, Telegraph uses the package's normal bot resolution rules.

Notification

Add telegraph to the notification's via() method and return a message from toTelegraph():

namespace App\Notifications;

use DefStudio\Telegraph\Notifications\TelegraphMessage;
use Illuminate\Notifications\Notification;

class ApplicationAlert extends Notification
{
    public function __construct(
        private readonly string $message,
    ) {
    }

    public function via(object $notifiable): array
    {
        return ['telegraph'];
    }

    public function toTelegraph(object $notifiable): TelegraphMessage
    {
        return TelegraphMessage::make($this->message)
            ->html()
            ->silent();
    }
}

For simple notifications, toTelegraph() may return a string:

public function toTelegraph(object $notifiable): string
{
    return 'The backup completed successfully.';
}

Message options

TelegraphMessage supports common message options:

return TelegraphMessage::make('Deploy failed')
    ->markdown()
    ->silent()
    ->withoutPreview()
    ->protectContent()
    ->inThread(42);

Available methods:

• ->html(): send the content using Telegram HTML parsing
• ->markdown(): send the content using Telegram Markdown parsing
• ->markdownV2(): send the content using Telegram MarkdownV2 parsing
• ->silent(): send the message without a notification sound
• ->withoutPreview(): disable link previews
• ->protectContent(): protect message content from forwarding and saving
• ->inThread(): send the notification to a forum topic thread
• ->bot(): set a bot token or TelegraphBot model for this message
• ->chat(): set a chat id or TelegraphChat model for this message

If no parse mode is selected, Telegraph uses telegraph.default_parse_mode.

Alerting from logs

For log-driven alerts, create a normal Laravel notification and send it only when the event is important enough for Telegram:

try {
    // ...
} catch (Throwable $exception) {
    Notification::route('telegraph', [
        'bot_token' => env('TELEGRAPH_BOT_TOKEN'),
        'chat_id' => env('TELEGRAPH_ALERT_CHAT_ID'),
    ])->notify(new ApplicationAlert($exception->getMessage()));

    throw $exception;
}

Avoid sending verbose debug logs, tokens, request bodies, passwords, or other secrets to Telegram.