Telegram Notification Channel for Laravel

This package plugs the Telegram Bot API into Laravel’s native notification system as a first-class channel, so a notification class can implement toTelegram() alongside toMail() or toDatabase() and get routed the same way. It wraps Guzzle to talk to the Bot API and exposes fluent builders for plain text, photos, documents, audio, video, locations, venues, contacts, polls, dice rolls, and media groups, plus inline and reply keyboards, all with Markdown/MarkdownV2/HTML parse modes.

Beyond simple text alerts, it handles the operational edges that make Telegram bots annoying to build from scratch: automatic message chunking past Telegram’s 4096-character limit, chat-ID resolution via routeNotificationFor() or on-demand routes, typed CouldNotSendNotification exceptions with static factory constructors for each failure mode, and hooks into Laravel’s NotificationFailed event plus a per-message onError callback. It’s maintained by the Laravel Notification Channels community org, which runs the same pattern across dozens of other providers (Slack, Discord, Twilio, etc.).

What You Get

• A TelegramChannel that integrates with Laravel’s ChannelManager so notifications route to Telegram the same way they route to mail or database channels
• Fluent message builders — TelegramMessage, TelegramFile, TelegramPoll, TelegramDice, TelegramLocation, TelegramVenue, TelegramContact, TelegramMediaGroup — each returning static for chaining
• Automatic long-message chunking (configurable limit, default 4096 chars) with a 1-second delay between chunks to respect Telegram rate limits
• Inline and reply keyboard builders, including request-contact and request-location keyboard buttons and callback-style buttons with success/danger styling
• Typed exception hierarchy (CouldNotSendNotification) with named static constructors for each failure case, plus a NotificationFailed event dispatch and an onError callback hook
• A TelegramUpdates helper for polling getUpdates to discover a recipient’s chat ID before you can message them

Common Use Cases

• Alerting an internal team Telegram channel when an order, invoice, or support ticket needs attention
• Sending transactional confirmations (OTPs, password resets, deployment status) to end users who’ve linked a Telegram chat ID to their account
• Building a lightweight admin bot that posts polls, keyboards, or media groups back to a Laravel-managed group chat
• Piping application error/exception alerts to an ops Telegram channel via a queued notification

Under The Hood

Architecture The package registers a Telegram HTTP client and a TelegramChannel through TelegramServiceProvider, which extends Laravel’s ChannelManager so via() returning 'telegram' routes straight to TelegramChannel::send(). That method reads toTelegram() off the notification, resolves the recipient chat ID (explicit to(), routeNotificationFor('telegram', ...), or a class-name fallback route), and dispatches through one of several TelegramBase-derived message classes (TelegramMessage, TelegramFile, TelegramPoll, etc.) that share payload-building logic via the HasSharedLogic trait and delegate the actual HTTP call to Telegram::sendMessage()/sendPhoto()/etc., which wrap Guzzle. Failures surface as CouldNotSendNotification, which the channel converts into a Laravel NotificationFailed event and an optional per-message onError callback, keeping HTTP concerns out of the notification classes entirely.

Tech Stack Requires PHP ^8.3 and Laravel 12/13 (illuminate/contracts, illuminate/notifications, illuminate/support), with guzzlehttp/guzzle ^7.8 as the sole HTTP dependency. Dev tooling is modern: Pest 4 with the Laravel plugin for tests, Orchestra Testbench for a sandboxed Laravel app, Larastan/PHPStan for static analysis (including a deprecation-rules extension), and Composer scripts wiring analyse and test directly to those tools.

Code Quality Every class uses declare(strict_types=1) and typed properties/return types throughout, with PHPStan-level generics documented via @phpstan-type annotations on payload shapes. The test suite in tests/Feature/ mirrors the src/ structure one-to-one (a spec file per message type plus the channel and service provider), using TestSupport/ notification fixtures rather than mocking Laravel internals directly. Exception handling is centralized in a single CouldNotSendNotification class with named static constructors per failure mode, avoiding scattered generic exceptions.

API Design The fluent, chainable builder pattern (TelegramMessage::create()->to()->content()->button()) keeps call sites terse and mirrors Laravel’s own notification-building idioms, so existing Laravel developers need almost no new mental model. Every message type follows the same to()/content()/send() shape, and optional behaviors (chunking, view rendering, markdown escaping) are opt-in fluent calls rather than constructor flags, which keeps the common case — a one-line text notification — genuinely simple.