DEV Community

Cover image for Laravel Telegram Cleanup: Auto-Delete Your Telegram Bot Messages
Mikhail Zakharov
Mikhail Zakharov

Posted on

Laravel Telegram Cleanup: Auto-Delete Your Telegram Bot Messages

#automation #laravel #php #showdev

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
Enter fullscreen mode Exit fullscreen mode

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'),
],
Enter fullscreen mode Exit fullscreen mode

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);
    }
}
Enter fullscreen mode Exit fullscreen mode

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));
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

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);
    }
}
Enter fullscreen mode Exit fullscreen mode

Configuration

Publish the configuration file to customize settings:

php artisan vendor:publish --tag=telegram-cleanup-config
Enter fullscreen mode Exit fullscreen mode

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']
);
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Database Cleanup

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

Schedule::command('telegram:messages:prune')
    ->weekly()
    ->withoutOverlapping();
Enter fullscreen mode Exit fullscreen mode

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

Links

I'd love to hear your feedback, issues, and pull requests! If you find this package useful — give it a star on GitHub ⭐

laravel #php #telegram #opensource

Top comments (0)