symfony/telegram-notifier

Symfony Telegram Notifier Bridge

v8.0.4 2026-01-05 09:27 UTC

Requires

• php: >=8.4
• symfony/http-client: ^7.4|^8.0
• symfony/mime: ^7.4|^8.0
• symfony/notifier: ^7.4|^8.0

MIT

• Fabien Potencier
• Symfony Community

• notifier
• telegram

README

Provides Telegram integration for Symfony Notifier.

DSN example

TELEGRAM_DSN=telegram://TOKEN@default?channel=CHAT_ID&sslmode=SSLMODE

where:

• TOKEN is your Telegram token
• CHAT_ID is your Telegram chat id
• SSLMODE https is used by default. It can be changed by setting value to disable, http will be used

Interacting with local API server instead of official Telegram API

If such a case is needed, you can replace the default keyword in the DSN with the desired domain/IP address of your local API server. You may also want to disable the bridge's default behavior of using https protocol as local API servers can only accept http traffic.

Example:

TELEGRAM_DSN=telegram://TOKEN@localhost:5001?channel=CHAT_ID&sslmode=disable

Caution: Disabling the use of the https protocol can pose a security risk. You should only do this if your local API server is hosted somehow internally and the traffic will remain within a secure environment.

Otherwise, you may want to implement a TLS-termination proxy in front of your server for handling the encryption and decryption of the traffic, So you can continue using it normally over https protocol.

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