telegram-bot-essentials/announcements

Bulk broadcast with live progress and retraction for telegram-bot-essentials/essence

v0.0.12 2026-09-01 12:19 UTC

Requires

• php: ^8.3
• laravel/framework: ^12 || ^13
• telegram-bot-essentials/essence: ^0.12

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.18
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^3.7 || ^4.0
• pestphp/pest-plugin-laravel: ^3.1 || ^4.0

MIT

• Elyar

Published on Packagist.org on 2026-09-02 09:05 UTC

README

Lets admins compose a message once and broadcast it to every bot user, or a filtered subset, on top of telegram-bot-essentials/essence. Broadcasts run with live progress, per-target delivery tracking, and can be retracted (deleted) afterwards — all without blocking the bot's normal interactive traffic.

Installation

composer require telegram-bot-essentials/announcements
php artisan migrate

# optional — change the queue name or batch size
php artisan vendor:publish --tag=tbe-announcements-config

Run a worker that processes the dedicated queue alongside your default one:

php artisan queue:work --queue=default,announcements

Announcements deliberately use their own low-priority queue so a broadcast to thousands of users can't starve interactive responses sharing the worker pool.

How it works

• Three delivery methods: html (freeform composed text), copy (re-send with no "Forwarded from" tag), forward (keep the tag).
• Targets are chunked into batch_size groups; one queued SendAnnouncementJob per chunk imports the WebhookContext across the queue boundary.
• Reachability is re-checked per target at send time — a user who unblocked the bot still gets the message; a known-unreachable user is skipped with no API call spent.
• Per-target status: sent / skipped / forbidden (user's fault — feeds botUserStatus()) / failed (transient — reachability untouched), then deleted after retraction.
• The live progress message is edited with an ASCII progress bar, throttled via a 3-second cache lock so concurrent job completions don't hit a rate limit.

Documentation

Full documentation — the data model, sending and retraction flows, and the WebhookContext export/import pattern — lives on the Telegram Bot Essentials documentation site under Modules → Announcements.

License

MIT.