asdrubalp9/laravel-telegram

Send Telegram messages from Laravel: channels, media, and queues.

v1.0.0 2026-06-02 08:52 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.5
• illuminate/http: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^9.0|^10.0
• phpunit/phpunit: ^11.0

MIT

• dru

• notifications
• bot
• laravel
• telegram

README

A Laravel package to send Telegram messages: multiple channels, media, and async queues.

Requirements

• PHP ^8.2
• Laravel ^11.0 or ^12.0

Installation

composer require asdrubalp9/laravel-telegram

Laravel's auto-discovery will register TelegramServiceProvider and the Telegram facade automatically.

Publish the config

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

Environment Variables

Add to your .env:

TELEGRAM_BOT_TOKEN=123456:ABC         # Global bot token
TELEGRAM_CHAT_ID=-1001112223334       # Default channel chat ID
TELEGRAM_CHAT_ERRORS=-1004445556667   # "errors" channel (uses global token)
TELEGRAM_ALERTS_TOKEN=999888:XYZ      # "alerts" channel — own bot token
TELEGRAM_ALERTS_CHAT=-1007778889990
TELEGRAM_PARSE_MODE=HTML              # HTML | Markdown | MarkdownV2
TELEGRAM_TIMEOUT=10                   # HTTP timeout in seconds
TELEGRAM_QUEUE=                       # Empty = synchronous; set to queue name for async by default
TELEGRAM_PREFIX_ENV=false             # Prepend [APP_ENV] to every message

Usage

Send a message (default channel)

use Asdrubalp9\Telegram\Facades\Telegram;

Telegram::send('Server started successfully.');

Use a named channel

Telegram::channel('errors')->send('Exception: something went wrong.');

Telegram::channel('alerts')->send('Disk usage above 90%.');

Override the chat ID on the fly

Telegram::channel('default')->to('-9999999999')->send('Direct message.');

Send media

// Photo by URL or file_id
Telegram::sendPhoto('https://example.com/chart.png', 'Monthly report');

// Document
Telegram::sendDocument('https://example.com/report.pdf', 'Q1 report');

// On a specific channel
Telegram::channel('alerts')->sendPhoto($fileId, 'Alert screenshot');

Async dispatch (queue)

// Explicit queue on a single message
Telegram::channel('errors')->queue()->send('Queued message');

// Use a specific queue connection
Telegram::channel('alerts')->queue('redis')->send('Redis-queued alert');

Setting TELEGRAM_QUEUE=default in .env makes all messages queue by default without calling ->queue() explicitly.

Parse mode and extra options

Telegram::channel('default')
    ->parseMode('MarkdownV2')
    ->options(['disable_notification' => true])
    ->send('*Bold text*');

Config: multiple channels

Edit config/telegram.php to add custom channels:

'channels' => [
    'default' => ['chat_id' => env('TELEGRAM_CHAT_ID')],
    'errors'  => ['chat_id' => env('TELEGRAM_CHAT_ERRORS')],
    'alerts'  => [
        'token'   => env('TELEGRAM_ALERTS_TOKEN'), // overrides global token
        'chat_id' => env('TELEGRAM_ALERTS_CHAT'),
    ],
],

Token resolution rule: channels.<name>.token ?? global token. If either token or chat_id is missing for the resolved channel, a TelegramException is thrown.

Testing

The package uses Http::fake() and Queue::fake() — no real Telegram API calls during tests.

vendor/bin/phpunit

Extend Asdrubalp9\Telegram\Tests\TestCase in your own package tests to inherit the pre-configured Testbench setup.

Publishing to Packagist

1. Push a tag: git tag v1.0.0 && git push --tags
2. Register the repo at packagist.org
3. Configure the GitHub webhook for automatic updates.

License

MIT — see LICENSE.