mrjavadseydi/notif-telegram

Telegram Notifications Channel for Laravel

dev-main 2022-01-20 08:27 UTC

Requires

• php: ^7.1
• guzzlehttp/guzzle: ^6.2
• illuminate/notifications: ^5.5 || ^6.0
• illuminate/support: ^5.5 || ^6.0

Requires (Dev)

• mockery/mockery: ^1.0
• phpunit/phpunit: ^7.0 || ^8.0

MIT

• Irfaq Syed

• notification
• laravel
• telegram
• telegram notification
• telegram notifications channel

README

Telegram Notifications Channel for Laravel

This package makes it easy to send Telegram notification using Telegram Bot API with Laravel.

Contents

• Installation
  • Setting up your Telegram bot
• Usage
  • Text Notification
  • Attach a Photo
  • Attach a Document
  • Attach a Location
  • Attach a Video
  • Attach a Gif File
  • Available Message methods
  • Available Location methods
  • Available File methods
• Alternatives
• Changelog
• Testing
• Security
• Contributing
• Credits
• License

Installation

You can install the package via composer:

composer require laravel-notification-channels/telegram

Setting up your Telegram Bot

Talk to @BotFather and generate a Bot API Token.

Then, configure your Telegram Bot API Token:

// config/services.php
...
'telegram-bot-api' => [
    'token' => env('TELEGRAM_BOT_TOKEN', 'YOUR BOT TOKEN HERE')
],
...

Usage

You can now use the channel in your via() method inside the Notification class.

Text Notification

use NotificationChannels\Telegram\TelegramChannel;
use NotificationChannels\Telegram\TelegramMessage;
use Illuminate\Notifications\Notification;

class InvoicePaid extends Notification
{
    public function via($notifiable)
    {
        return [TelegramChannel::class];
    }

    public function toTelegram($notifiable)
    {
        $url = url('/invoice/' . $this->invoice->id);

        return TelegramMessage::create()
            // Optional recipient user id.
            ->to($notifiable->telegram_user_id)
            // Markdown supported.
            ->content("Hello there!\nYour invoice has been *PAID*")
            // (Optional) Inline Buttons
            ->button('View Invoice', $url)
            ->button('Download Invoice', $url);
    }
}

Here's a screenshot preview of the above notification on Telegram Messenger:

Attach a Photo

public function toTelegram($notifiable)
{
    $url = url('/file/' . $this->file->id);

    return TelegramFile::create()
        ->to($notifiable->telegram_user_id)
        ->content('Awesome *bold* text and [inline URL](http://www.example.com/)')
        ->file('/storage/archive/6029014.jpg', 'photo'); // local photo

        // OR using a helper method with or without a remote file.
        // ->photo('https://file-examples.com/wp-content/uploads/2017/10/file_example_JPG_1MB.jpg');
}

Preview:

Attach a Document

public function toTelegram($notifiable)
{
    $url = url('/file/' . $this->file->id);

    return TelegramFile::create()
        ->to($notifiable->telegram_user_id)
        ->content('Did you know we can set a custom filename too?')
        ->document('https://file-examples.com/wp-content/uploads/2017/10/file-sample_150kB.pdf', 'sample.pdf');
}

Preview:

Attach a Location

public function toTelegram($notifiable)
{
    return TelegramLocation::create()
        ->to($notifiable->telegram_user_id)
        ->latitude('40.6892494')
        ->longitude('-74.0466891');
}

Preview:

Attach a Video

public function toTelegram($notifiable)
{
    return TelegramFile::create()
        ->to($notifiable->telegram_user_id)
        ->content('Sample *video* notification!')
        ->video('https://file-examples.com/wp-content/uploads/2017/04/file_example_MP4_480_1_5MG.mp4');
}

Preview:

Attach a Gif File

public function toTelegram($notifiable)
{
    return TelegramFile::create()
        ->content('Woot! We can send animated gif notifications too!')
        ->animation('https://sample-videos.com/gif/2.gif');

        // Or local file
        // ->animation('/path/to/some/animated.gif');
}

Preview:

Routing a message

You can either send the notification by providing with the chat id of the recipient to the to($chatId) method like shown in the above example or add a routeNotificationForTelegram() method in your notifiable model:

...
/**
 * Route notifications for the Telegram channel.
 *
 * @return int
 */
public function routeNotificationForTelegram()
{
    return $this->telegram_user_id;
}
...

Available Message methods

• to($chatId): (integer) Recipient's chat id.
• content(''): (string) Notification message, supports markdown. For more information on supported markdown styles, check out these docs.
• button($text, $url): (string) Adds an inline "Call to Action" button. You can add as many as you want and they'll be placed 2 in a row.
• disableNotification(): Send the message silently. Users will receive a notification with no sound.
• options([]): (array) Allows you to add additional or override sendMessage payload (A Telegram Bot API method used to send message internally). For more information on supported parameters, check out these docs.

Available Location methods

• to($chatId): (integer) Recipient's chat id.
• latitude($latitude): (float|string) Latitude of the location.
• longitude($longitude): (float|string) Longitude of the location.
• button($text, $url): (string) Adds an inline "Call to Action" button. You can add as many as you want and they'll be placed 2 in a row.
• disableNotification(): Send the message silently. Users will receive a notification with no sound.
• options([]): (array) Allows you to add additional or override the payload.

Available File methods

• to($chatId): (integer) Recipient's chat id.
• content(''): (string) File caption, supports markdown. For more information on supported markdown styles, check out these docs.
• file($file, $type, $filename = null): Local file path or remote URL, $type of the file (Ex:photo, audio, document, video, animation, voice, video_note_) and optionally filename with extension. Ex: sample.pdf. You can use helper methods instead of using this to make it easier to work with file attachment.
• photo($file): Helper method to attach a photo.
• audio($file): Helper method to attach an audio file (MP3 file).
• document($file, $filename = null): Helper method to attach a document or any file as document.
• video($file): Helper method to attach a video file.
• animation($file): Helper method to attach an animated gif file.
• voice($file): Helper method to attach a voice note (.ogg file with OPUS encoded).
• videoNote($file): Helper method to attach a video note file (Upto 1 min long, rounded square video).
• button($text, $url): (string) Adds an inline "Call to Action" button. You can add as many as you want and they'll be placed 2 in a row.
• disableNotification(): Send the message silently. Users will receive a notification with no sound.
• options([]): (array) Allows you to add additional or override the payload.

Alternatives

For advance usage, please consider using telegram-bot-sdk instead.

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Contributing

Please see CONTRIBUTING for details.

Credits

• Irfaq Syed
• All Contributors

License

The MIT License (MIT). Please see License File for more information.