Weave Code
Telegram Laravel Package
laravel-notification-channels/telegram
Send Telegram notifications from Laravel using the Telegram Bot API. Supports text messages, inline keyboards, dice, polls, media groups, photos, documents, locations, contacts, stickers and more, plus message routing, response handling and direct client access.
Telegram Notifications Channel for Laravel makes it easy to send messages via the Telegram Bot API using Laravel's native notification system. Install it, create a bot with @BotFather, grab a chat ID, and you can notify users through any Laravel notifiable model or on-demand notifications.
- Send text, photos, documents, audio, video, GIFs, stickers, contacts, locations, and venues
- Build interactive messages with inline keyboards, polls, and dice
- Deliver media groups and rich messages with streaming drafts
- Handle failures via NotificationFailed events or the onError callback
- Route, proxy, and send to multiple recipients with a fluent, chainable API
Frequently asked questions about Telegram
- How do I install the Telegram notification channel in Laravel?
- Install it with Composer using composer require laravel-notification-channels/telegram. Then publish the package configuration with php artisan vendor:publish. After that, set your bot token and chat ID in the published configuration before sending your first notification.
- How do I configure the Telegram bot token and chat ID?
- Create a bot with BotFather, then store the bot token in your Laravel configuration or environment. Retrieve the target chat ID and set it in the published Telegram configuration or pass it through the notification route. The package also lets you tune HTTP behavior through services.telegram.http if you need different timeout values.
- Which Laravel versions are supported by this package?
- The provided overview does not list exact Laravel or PHP version constraints. Check the package's composer.json and Packagist metadata for the current supported ranges before upgrading. The channel is built as a native Laravel notification channel, so it follows Laravel notification conventions rather than requiring schema changes.
- What breaking changes should I audit before upgrading to 8.0.0?
- Version 8.0.0 contains six marked breaking changes, so treat it as an upgrade project rather than a drop-in bump. Audit code that relies on escapedLine() semantics, unknown file types silently becoming documents, null checks on client methods or TelegramSenderContract::send(), and pre-encoded JSON in form parameters. Array values in form params are now JSON-encoded, and escapedLine() escapes according to the active parse mode. Test copy and notification classes that touch those paths before deploying.
- How do I send rich Telegram messages with tables, lists, or math?
- Use TelegramRichMessage with the package's block builders such as table(), listBlock(), math(), collage, slideshow, and media blocks. Rich messages target Bot API 10.1 and 10.2 features and can include RTL and entity flags. Treat these message templates like email templates: assign ownership and review them before using them for reports, receipts, or digests.
- Can I stream AI-generated answers into Telegram with rich message drafts?
- Yes, TelegramRichMessageDraft is designed for streaming AI-generated answers into a Telegram message. Drafts are limited to private chats with a non-zero draft id, so your design must guarantee a one-to-one user and bot context. That excludes group and channel use cases, so do not use drafts for shared or broadcast conversations.
- How do I send photos, documents, or media groups from Laravel?
- The channel supports photos, audio, documents, locations, venues, video, GIFs, stickers, and media groups. Use TelegramFile::fileId() or TelegramFile::url() when you need explicit file attachments. For multi-file messages, use the media group methods and keep file identifiers or URLs in configuration or storage rather than hard-coding them.
- How do I handle Telegram notification failures and exceptions?
- Handle channel failures through Laravel's NotificationFailed event or the onError callback shown in the README. The package exposes specific exceptions such as invalidFileType(), invalidFileIdentifier(), invalidRichMessageDraftId(), and richMessageDraftIdNotProvided() for cleaner failure routing. Use those exceptions to separate configuration errors, bad attachments, and draft misuse in your logs or alerting.
- How do I test Telegram notifications in a Laravel application?
- Use Laravel's Notification::fake() to assert that your notification is dispatched without calling the Telegram API. Review the package's Testing section and repository tests for channel-specific patterns, and inject a test double where your code uses the Telegram client directly. Keep tests for rich message templates separate so content changes do not silently break notification behavior.
- What should I know about Telegram timeouts and 429 retries in production?
- Version 8.0.0 adds default Guzzle timeouts of 30 seconds total and 10 seconds to connect, which can turn previous indefinite hangs into exceptions. The package automatically retries a 429 response only when retry_after is 60 seconds or less, and only once. Configure your queue backoff to cover longer waits and tune services.telegram.http for large media or slow links.
Weaver
How can I help you explore Laravel packages today?