Laravel Telegram Cleanup: Auto-Delete Your Telegram Bot Messages

Mikhail Zakharov — Wed, 28 Jan 2026 07:48:26 +0000

Hey there! Today I want to share my open-source Laravel package that solves a simple but important task — automatically deleting Telegram bot messages after a specified time.

Why Do You Need This?

If you work with Telegram bots in Laravel, you've probably encountered situations where messages should have a limited lifespan:

Verification codes — you send a code, the user enters it, but the message with the code stays in the chat forever
Temporary notifications — reminders, alerts, status updates that become irrelevant over time
One-time passwords (OTP) — for security reasons, it's better to delete them immediately after use
Promo messages — limited-time offers and promotions

Sure, you could implement this manually: save message_id, write deletion commands, handle Telegram API rate limits... But why bother when you can just install a package?

Installation

composer require rud99/laravel-telegram-cleanup
php artisan migrate

The package extends the popular laravel-notification-channels/telegram, so if you're already using it — setup is minimal. Just make sure your bot token is configured in config/services.php:

'telegram-bot-api' => [
    'token' => env('TELEGRAM_BOT_TOKEN'),
],

How to Use

1. Create a Notification

Extend TelegramCleanupNotification instead of the standard Notification:

use Rud99\TelegramCleanup\Notifications\TelegramCleanupNotification;
use NotificationChannels\Telegram\TelegramMessage;

class VerificationCodeNotification extends TelegramCleanupNotification
{
    public function __construct(
        protected string $code,
        ?int $deleteAfterMinutes = 5
    ) {
        $this->deleteAfterMinutes = $deleteAfterMinutes;
        $this->message = "Your code: {$code}";
        $this->meta = ['type' => 'verification'];
    }

    public function toTelegram(object $notifiable): TelegramMessage
    {
        return TelegramMessage::create()
            ->content($this->message);
    }
}

2. Send It

use Illuminate\Support\Facades\Notification;

// Via queue (recommended)
Notification::route('telegram', $chatId)
    ->notify(new VerificationCodeNotification('1234', 5));

// Synchronously
Notification::route('telegram', $chatId)
    ->notifyNow(new VerificationCodeNotification('1234', 5));

The message will be automatically deleted after 5 minutes. That's it!

3. Set Up the Scheduler

Add the cleanup command to routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('telegram:messages:delete-expired')
    ->everyFiveMinutes()
    ->withoutOverlapping();

Flexible TTL Configuration

The package supports three behavior options:

Value	Behavior
`null` (not set)	Uses default from config (24 hours)
`false`	Auto-delete disabled — message stays forever
`N` (integer)	Delete after N minutes

Example of a notification that never gets deleted:

class ImportantNotification extends TelegramCleanupNotification
{
    public function __construct(protected string $text)
    {
        $this->deleteAfterMinutes = false; // Never delete
        $this->message = $text;
    }

    public function toTelegram(object $notifiable): TelegramMessage
    {
        return TelegramMessage::create()->content($this->text);
    }
}

Configuration

Publish the configuration file to customize settings:

php artisan vendor:publish --tag=telegram-cleanup-config

Available options in config/telegram-cleanup.php:

Option	Default	Description
`default_delete_after_minutes`	1440	Default TTL (24 hours)
`delay_between_requests_ms`	150	Delay between API calls (rate limit)
`max_retry_attempts`	3	Retry attempts on 429 errors
`prune_after_months`	1	Keep deleted message records for N months

Additional Features

Manual Message Registration

If you're sending messages without Laravel's notification system:

use Rud99\TelegramCleanup\TelegramMessageCleanupService;

$service = app(TelegramMessageCleanupService::class);

$service->registerForDeletion(
    chatId: $chatId,
    messageId: $messageId,
    deleteAfterMinutes: 30,
    meta: ['type' => 'manual']
);

Artisan Commands

# Delete expired messages
php artisan telegram:messages:delete-expired

# Preview without deleting
php artisan telegram:messages:delete-expired --dry-run

# Limit number of deletions
php artisan telegram:messages:delete-expired --limit=100

# Delete only from a specific chat
php artisan telegram:messages:delete-expired --chat-id=123456789

# Prune old records from database
php artisan telegram:messages:prune

Database Cleanup

To prevent the message history table from growing indefinitely, add to your scheduler:

Schedule::command('telegram:messages:prune')
    ->weekly()
    ->withoutOverlapping();

Under the Hood

The package:

Creates a table to store information about messages scheduled for deletion
Automatically registers sent messages via Event Listener
Respects Telegram API rate limits (configurable delay between requests)
Handles 429 errors with automatic retries
Stores meta information for debugging

laravel #php #telegram #opensource

Forem: Mikhail Zakharov