symfony/telegram-notifier

Symfony Telegram Notifier Bridge

v7.2.0 2024-10-25 15:15 UTC

Requires

• php: >=8.2
• symfony/http-client: ^6.4|^7.0
• symfony/mime: ^6.4|^7.0
• symfony/notifier: ^7.2

MIT

• Fabien Potencier
• Symfony Community

• notifier
• telegram

README

Provides Telegram integration for Symfony Notifier.

DSN example

TELEGRAM_DSN=telegram://TOKEN@default?channel=CHAT_ID

where:

• TOKEN is your Telegram token
• CHAT_ID is your Telegram chat id

Adding Interactions to a Message

With a Telegram message, you can use the TelegramOptions class to add message options.

use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\Button\InlineKeyboardButton;
use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\InlineKeyboardMarkup;
use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
use Symfony\Component\Notifier\Message\ChatMessage;

$chatMessage = new ChatMessage('');

// Create Telegram options
$telegramOptions = (new TelegramOptions())
    ->chatId('@symfonynotifierdev')
    ->parseMode('MarkdownV2')
    ->disableWebPagePreview(true)
    ->disableNotification(true)
    ->replyMarkup((new InlineKeyboardMarkup())
        ->inlineKeyboard([
            (new InlineKeyboardButton('Visit symfony.com'))
                ->url('https://symfony.com/'),
        ])
    );

// Add the custom options to the chat message and send the message
$chatMessage->options($telegramOptions);

$chatter->send($chatMessage);

Adding files to a Message

With a Telegram message, you can use the TelegramOptions class to add message options.

⚠️ WARNING In one message you can send only one file

Telegram supports 3 ways for passing files:

• You can send files by passing public http url to option:
  • Photo

    $telegramOptions = (new TelegramOptions())
         ->photo('https://localhost/photo.mp4');

  • Video

    $telegramOptions = (new TelegramOptions())
         ->video('https://localhost/video.mp4');

  • Animation

    $telegramOptions = (new TelegramOptions())
         ->animation('https://localhost/animation.gif');

  • Audio

    $telegramOptions = (new TelegramOptions())
         ->audio('https://localhost/audio.ogg');

  • Document

    $telegramOptions = (new TelegramOptions())
         ->document('https://localhost/document.odt');

  • Sticker

    $telegramOptions = (new TelegramOptions())
         ->sticker('https://localhost/sticker.webp', '🤖');

• You can send files by passing local path to option, in this case file will be sent via multipart/form-data:
  • Photo

    $telegramOptions = (new TelegramOptions())
         ->uploadPhoto('files/photo.png');

  • Video

    $telegramOptions = (new TelegramOptions())
         ->uploadVideo('files/video.mp4');

  • Animation

        $telegramOptions = (new TelegramOptions())
             ->uploadAnimation('files/animation.gif');

  • Audio

    $telegramOptions = (new TelegramOptions())
         ->uploadAudio('files/audio.ogg');

  • Document

    $telegramOptions = (new TelegramOptions())
         ->uploadDocument('files/document.odt');

  • Sticker

    $telegramOptions = (new TelegramOptions())
         ->uploadSticker('files/sticker.webp', '🤖');

• You can send files by passing file_id to option:
  • Photo

    $telegramOptions = (new TelegramOptions())
         ->photo('ABCDEF');

  • Video

    $telegramOptions = (new TelegramOptions())
         ->video('ABCDEF');

  • Animation

    $telegramOptions = (new TelegramOptions())
         ->animation('ABCDEF');

  • Audio

    $telegramOptions = (new TelegramOptions())
         ->audio('ABCDEF');

  • Document

    $telegramOptions = (new TelegramOptions())
         ->document('ABCDEF');

  • Sticker - Can't be sent using file_id

Full example:

use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
use Symfony\Component\Notifier\Message\ChatMessage;

$chatMessage = new ChatMessage('Photo Caption');

// Create Telegram options
$telegramOptions = (new TelegramOptions())
    ->chatId('@symfonynotifierdev')
    ->parseMode('MarkdownV2')
    ->disableWebPagePreview(true)
    ->hasSpoiler(true)
    ->protectContent(true)
    ->photo('https://symfony.com/favicons/android-chrome-192x192.png');

// Add the custom options to the chat message and send the message
$chatMessage->options($telegramOptions);

$chatter->send($chatMessage);

Adding Location to a Message

With a Telegram message, you can use the TelegramOptions class to add message options.

use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
use Symfony\Component\Notifier\Message\ChatMessage;

$chatMessage = new ChatMessage('');

// Create Telegram options
$telegramOptions = (new TelegramOptions())
    ->chatId('@symfonynotifierdev')
    ->parseMode('MarkdownV2')
    ->location(48.8566, 2.3522);

// Add the custom options to the chat message and send the message
$chatMessage->options($telegramOptions);

$chatter->send($chatMessage);

Adding Venue to a Message

With a Telegram message, you can use the TelegramOptions class to add message options.

use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
use Symfony\Component\Notifier\Message\ChatMessage;

$chatMessage = new ChatMessage('');

// Create Telegram options
$telegramOptions = (new TelegramOptions())
    ->chatId('@symfonynotifierdev')
    ->parseMode('MarkdownV2')
    ->venue(48.8566, 2.3522, 'Center of Paris', 'France, Paris');

// Add the custom options to the chat message and send the message
$chatMessage->options($telegramOptions);

$chatter->send($chatMessage);

Adding Contact to a Message

With a Telegram message, you can use the TelegramOptions class to add message options.

use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
use Symfony\Component\Notifier\Message\ChatMessage;

$chatMessage = new ChatMessage('');

$vCard = 'BEGIN:VCARD
VERSION:3.0
N:Doe;John;;;
FN:John Doe
EMAIL;type=INTERNET;type=WORK;type=pref:[e-mail]
TEL;type=WORK;type=pref:[phone]
END:VCARD';

// Create Telegram options
$telegramOptions = (new TelegramOptions())
    ->chatId('@symfonynotifierdev')
    ->parseMode('MarkdownV2')
    ->contact('[phone]', 'John', 'Doe', $vCard);

// Add the custom options to the chat message and send the message
$chatMessage->options($telegramOptions);

$chatter->send($chatMessage);

Updating Messages

The TelegramOptions::edit() method was introduced in Symfony 6.2.

When working with interactive callback buttons, you can use the TelegramOptions to reference a previous message to edit.

use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\Button\InlineKeyboardButton;
use Symfony\Component\Notifier\Bridge\Telegram\Reply\Markup\InlineKeyboardMarkup;
use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
use Symfony\Component\Notifier\Message\ChatMessage;

$chatMessage = new ChatMessage('Are you really sure?');
$telegramOptions = (new TelegramOptions())
    ->chatId($chatId)
    ->edit($messageId) // extracted from callback payload or SentMessage
    ->replyMarkup((new InlineKeyboardMarkup())
        ->inlineKeyboard([
            (new InlineKeyboardButton('Absolutely'))->callbackData('yes'),
        ])
    );

Answering Callback Queries

The TelegramOptions::answerCallbackQuery() method was introduced in Symfony 6.3.

When sending message with inline keyboard buttons with callback data, you can use TelegramOptions to answer callback queries.

use Symfony\Component\Notifier\Bridge\Telegram\TelegramOptions;
use Symfony\Component\Notifier\Message\ChatMessage;

$chatMessage = new ChatMessage('Thank you!');
$telegramOptions = (new TelegramOptions())
    ->chatId($chatId)
    ->answerCallbackQuery(
        callbackQueryId: '12345', // extracted from callback
        showAlert: true,
        cacheTime: 1,
    );

Resources

• Contributing
• Report issues and send Pull Requests in the main Symfony repository