Download the PHP package laravel-notification-channels/telegram without Composer

Telegram Notifications Channel for Laravel

This package makes it easy to send Telegram notifications from Laravel via the Telegram Bot API.

Contents

• Installation
  • Setting up your Telegram Bot
  • Retrieving Chat ID
  • Using in Lumen
  • Proxy or Bridge Support
• Usage
  • Text Notification
  • Send with Keyboard
  • Send a Dice
  • Send a Poll
  • Attach a Contact
  • Attach an Audio
  • Attach a Photo
  • Attach a Document
  • Attach a Location
  • Attach a Venue
  • Attach a Video
  • Attach a GIF File
  • Attach a Sticker
  • Send a Media Group
  • Routing a Message
  • Handling Response
  • Exception Handling
  • Using NotificationFailed Event
  • Using onError Callback
  • On-Demand Notifications
  • Sending to Multiple Recipients
  • Using the Telegram Client Directly
• Available Methods
  • Common Methods
  • Telegram Message Methods
  • Telegram Location Methods
  • Telegram Venue Methods
  • Telegram File Methods
  • Telegram Media Group Methods
  • Telegram Contact Methods
  • Telegram Dice Methods
  • Telegram Poll Methods
• Alternatives
• Changelog
• Testing
• Security
• Contributing
• Credits
• License

Installation

You can install the package via composer:

Setting up your Telegram Bot

Talk to @BotFather and generate a Bot API token.

Then, configure your Telegram Bot API token:

[!NOTE] The package also supports the legacy services.telegram-bot-api.* config keys for backward compatibility, but services.telegram.* is the preferred configuration format.

Retrieving Chat ID

To send notifications to a Telegram user, channel, or group, you need its chat ID.

You can retrieve it by fetching your bot updates with the getUpdates method described in the Telegram Bot API docs.

An update is an object whose shape depends on the event type, such as message, callback_query, or poll. For the full list of fields, see the Telegram Bot API docs.

To make this easier, the package ships with TelegramUpdates, which lets you fetch updates and inspect the chat IDs you need.

Keep in mind that the user must interact with your bot first before you can obtain their chat ID and store it for future notifications.

Here's an example of fetching an update:

[!NOTE] This method will not work while an outgoing webhook is configured.

For the full list of supported options(), see the Telegram Bot API docs.

Using in Lumen

If you're using this notification channel in your Lumen project, you will have to add the below code in your bootstrap/app.php file.

Proxy or Bridge Support

You may not be able to send notifications directly if the Telegram Bot API is blocked in your region. In that case, you can either configure a proxy by following the Guzzle instructions here or point the package at a bridge or self-hosted Bot API server by setting the base_uri config shown above.

You can also set HTTPS_PROXY in your .env file.

Usage

You can now return the channel from your notification's via() method.

Text Notification

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

Send with Keyboard

Preview:

You can also request structured input from the keyboard:

Preview:

Send a Dice

Preview:

Send a Poll

Preview:

Attach a Contact

Preview:

Attach an Audio

Preview:

Attach a Photo

You can also use a helper method with a remote file or Telegram file ID:

Preview:

Attach a Document

Preview:

If you want to control the filename, you need to upload the actual file contents instead of passing the remote URL directly:

Preview:

Raw file contents are also supported when you provide a filename:

Preview:

Attach a Location

Preview:

You can also send live location

Preview:

Attach a Venue

Preview:

Attach a Video

Preview:

Attach a GIF File

Local files work the same way:

Preview:

Attach a Sticker

Preview:

Send a Media Group

Use TelegramMediaGroup to send multiple items in a single group.

Uploaded files are also supported:

Preview:

Documents are also supported, including dynamically generated content:

Preview:

Supported Input Types

Each media item can be provided as:

• A Telegram file ID
• A remote URL
• A local file path
• A stream or resource
• Raw file contents (requires a filename)

When uploading local files or raw content, the package automatically handles multipart uploads.

Media groups support albums of photo, video, audio, and document items.

[!NOTE] Telegram does not allow mixing certain media types within a single group. Documents cannot be combined with photos or videos. However, photos and videos can be sent together in the same media group.

Routing a Message

You can either send a notification by setting the recipient explicitly with to($chatId) as shown above, or define routeNotificationForTelegram() on your notifiable model:

Handling Response

You can use notification events to handle Telegram responses. On success, your listener receives a Message object with fields appropriate to the notification type.

For the full list of response fields, refer to the Telegram Bot API Message object docs.

Exception Handling

For failures, the package provides two exception-handling hooks.

Using NotificationFailed Event

You can listen to Illuminate\Notifications\Events\NotificationFailed, which provides a $data array containing to, request, and exception keys.

Listener example:

Using onError Callback

You can handle exceptions for an individual notification by attaching an onError callback:

In both methods, the $data array contains the following keys:

• to: The recipient's chat ID.
• request: The payload sent to the Telegram Bot API.
• exception: The exception object containing error details.

On-Demand Notifications

Sometimes you may want to send a Telegram notification to someone who is not stored as a notifiable model. With Notification::route, you can provide ad-hoc routing information before dispatching the notification. For more details, see the on-demand notifications docs.

Sending to Multiple Recipients

Using the notification facade, you can send a notification to multiple recipients at once.

[!WARNING] If you're sending bulk notifications to many users, the Telegram Bot API will not allow much more than 30 messages per second. Consider spreading out notifications over large intervals of 8—12 hours for best results.

Also note that your bot will not be able to send more than 20 messages per minute to the same group.

If you go over the limit, you'll start getting 429 errors. For more details, refer Telegram Bots FAQ.

Using the Telegram Client Directly

If you need lower-level Bot API access, you can resolve the Telegram client directly from the container:

Available direct client helpers currently include:

• sendMessage(array $params)
• sendFile(array $params, string $type, bool $multipart = false)
• sendMediaGroup(array $params, bool $multipart = false)
• sendPoll(array $params)
• sendContact(array $params)
• sendLocation(array $params)
• sendVenue(array $params)
• sendDice(array $params)
• sendChatAction(array $params)
• editMessageText(array $params)
• editMessageCaption(array $params)
• editMessageMedia(array $params, bool $multipart = false)
• editMessageReplyMarkup(array $params)
• stopPoll(array $params)
• deleteMessage(array $params)
• deleteMessages(array $params)
• getUpdates(array $params)

Available Methods

For more information on supported parameters, check out these docs.

Common Methods

These methods are optional and common across all the API methods.

• to(int|string $chatId) - Set recipient's chat ID.
• token(string $token) - Override default bot token.
• parseMode(enum ParseMode $mode) - Set message parse mode (or normal() to unset). Default is ParseMode::Markdown.
• keyboard(string $text, int $columns = 2, bool $requestContact = false, bool $requestLocation = false) - Add regular keyboard. You can add as many as you want, and they'll be placed 2 in a row by default.
• button(string $text, string $url, int $columns = 2, ?string $style = null) - Add inline CTA button. Optional style: 'danger' (red), 'success' (green), 'primary' (blue).
• buttonWithCallback(string $text, string $callbackData, int $columns = 2, ?string $style = null) - Add inline button with callback.
• buttonWithWebApp(string $text, string $url, int $columns = 2, ?string $style = null) - Add inline web app button.
• disableNotification(bool $disableNotification = true) - Send silently (notification without sound).
• businessConnectionId(string $businessConnectionId) - Send on behalf of a connected business account.
• messageThreadId(int $messageThreadId) - Send to a forum / topic thread.
• directMessagesTopicId(int $directMessagesTopicId) - Send to a channel direct message topic.
• protectContent(bool $protect = true) - Protect content from forwarding and saving.
• allowPaidBroadcast(bool $allow = true) - Allow paid high-throughput broadcasts.
• messageEffectId(string $messageEffectId) - Add a private-chat message effect.
• replyParameters(array $replyParameters) - Set structured reply parameters.
• suggestedPostParameters(array $suggestedPostParameters) - Set suggested post parameters for supported direct message topics.
• options(array $options) - Add/override payload parameters.
• sendWhen(bool $condition) - Set condition for sending. If the condition is true, the notification will be sent; otherwise, it will not.
• onError(callable $callback) - Set error handler (receives a data array with to, request, exception keys).
• getPayloadValue(string $key) - Get specific payload value.

Telegram Message Methods

Telegram message notifications are used to send text messages to the user. Supports Telegram formatting options

• content(string $content, int $limit = null) - Set message content with optional length limit. Supports markdown.
• line(string $content) - Add new line of content.
• lineIf(bool $condition, string $content) - Conditionally add new line.
• escapedLine(string $content) - Add escaped content line (for Markdown).
• view(string $view, array $data = [], array $mergeData = []) - Use Blade template with Telegram supported HTML or Markdown syntax content if you wish to use a view file instead of the content() method.
• entities(array $entities) - Set explicit message entities instead of using parse_mode.
• linkPreviewOptions(array $linkPreviewOptions) - Set Telegram link preview options.
• chunk(int $limit = 4096) - Split long messages (rate limited to 1/second).

[!NOTE] Chunked messages will be rate limited to one message per second to comply with rate limitation requirements from Telegram.

Helper Methods:

• escapeMarkdown(string $content) - Escape a string to make it safe for the markdownv2 parse mode

Telegram Location Methods

Telegram location messages are used to share a geographical location with the user.

• latitude(float|string $latitude) - Set location latitude.
• longitude(float|string $longitude) - Set location longitude.
• horizontalAccuracy(float|int|string $horizontalAccuracy) - Set the location accuracy radius in meters.
• livePeriod(int $livePeriod) - Set the live location period in seconds.
• heading(int $heading) - Set the movement direction in degrees.
• proximityAlertRadius(int $proximityAlertRadius) - Set the proximity alert radius in meters.

Telegram Venue Methods

Telegram venue messages are used to share a geographical location information about a venue.

• latitude(float|string $latitude) - Set venue latitude.
• longitude(float|string $longitude) - Set venue longitude.
• title(string $title) - Set venue name/title.
• address(string $address) - Set venue address.
• foursquareId(string $foursquareId) - (Optional) Set Foursquare identifier of the venue.
• foursquareType(string $foursquareType) - (Optional) Set Foursquare type of the venue, if known.
• googlePlaceId(string $googlePlaceId) - (Optional) Set Google Places identifier of the venue.
• googlePlaceType(string $googlePlaceType) - (Optional) Set Google Places type of the venue.

Telegram File Methods

Telegram file messages are used to share various types of files with the user.

• content(string $content) - Set file caption. Supports markdown.
• view(string $view, array $data = [], array $mergeData = []) - Use Blade template for caption.
• captionEntities(array $captionEntities) - Set explicit caption entities.
• showCaptionAboveMedia(bool $show = true) - Show caption above supported media types.
• file(string|resource|StreamInterface $file, FileType|string $type, string $filename = null) - Attach a local path, remote URL, Telegram file ID, stream/resource, or raw file contents. Types: photo, audio, document, video, animation, voice, video_note, sticker (use Enums\FileType). Pass a filename when the string represents raw file contents.

Helper Methods:

• photo(string $file) - Send photo.
• audio(string $file) - Send audio (MP3).
• document(string $file, string $filename = null) - Send document or any file as document.
• video(string $file) - Send video.
• animation(string $file) - Send animated GIF.
• voice(string $file) - Send voice note (OGG/OPUS).
• videoNote(string $file) - Send video note (≤1min, rounded square video).
• sticker(string $file) - Send sticker (static PNG/WEBP, animated .TGS, or video .WEBM stickers).

Telegram Media Group Methods

Telegram media groups are albums of photo, video, audio, or document items sent as a single notification.

• photo(string|resource|StreamInterface $media, string $caption = null, string $filename = null) - Add a photo to the group.
• video(string|resource|StreamInterface $media, string $caption = null, string $filename = null) - Add a video to the group.
• audio(string|resource|StreamInterface $media, string $caption = null, string $filename = null) - Add an audio file to the group.
• document(string|resource|StreamInterface $media, string $caption = null, string $filename = null) - Add a document to the group.
• hasAttachments() - Determine if the group contains uploaded files and requires multipart transport.

Each media item may be a Telegram file ID, a URL, a local path, a stream/resource, or raw file contents when paired with a filename.

Telegram Contact Methods

Telegram contact messages are used to share contact information with the user.

• phoneNumber(string $phone) - Set contact phone.
• firstName(string $name) - Set contact first name.
• lastName(string $name) - Set contact last name (optional).
• vCard(string $vcard) - Set contact vCard (optional).

Telegram Dice Methods

Telegram dice messages are interactive emoji dice / darts / slots / bowling style messages.

• emoji(string $emoji) - Set the dice emoji (🎲, 🎯, 🎳, 🏀, ⚽, 🎰, etc.).

Telegram Poll Methods

Telegram polls are a type of interactive message that allows users to vote on a question. Polls can be used to gather feedback, make decisions, or even run contests.

• question(string $question) - Set poll question.
• choices(array $choices) - Set poll choices.

Alternatives

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

Changelog

Please see CHANGELOG for details about recent changes.

Testing

Security

If you discover any security related issues, please email [email protected] 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.