You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -351,10 +354,69 @@ public function routeNotificationForTelegram()
351
354
352
355
### Handling Response
353
356
354
-
You can make use of the [notification events](https://laravel.com/docs/10.x/notifications#notification-events) to handle the response from Telegram. On success, your event listener will receive a [Message](https://core.telegram.org/bots/api#message) object with various fields as appropriate to the notification type.
357
+
You can make use of the [notification events](https://laravel.com/docs/11.x/notifications#notification-events) to handle the response from Telegram. On success, your event listener will receive a [Message](https://core.telegram.org/bots/api#message) object with various fields as appropriate to the notification type.
355
358
356
359
For a complete list of response fields, please refer the Telegram Bot API's [Message object](https://core.telegram.org/bots/api#message) docs.
357
360
361
+
### Exception Handling
362
+
363
+
In case of failures, the package provides two ways to handle exceptions.
364
+
365
+
#### Using NotificationFailed Event
366
+
367
+
You can listen to the `Illuminate\Notifications\Events\NotificationFailed` event, which provides a `$data` array containing `to`, `request`, and `exception` keys.
368
+
369
+
Listener example:
370
+
```php
371
+
use Illuminate\Notifications\Events\NotificationFailed;
372
+
373
+
class HandleNotificationFailure
374
+
{
375
+
public function handle(NotificationFailed $event)
376
+
{
377
+
// $event->notification: The notification instance.
378
+
// $event->notifiable: The notifiable entity who received the notification.
379
+
// $event->channel: The channel name.
380
+
// $event->data: The data needed to process this failure.
381
+
382
+
if ($event->channel !== 'telegram') {
383
+
return;
384
+
}
385
+
386
+
// Log the error / notify administrator or disable notification channel for the user, etc.
You can handle exceptions for individual notifications using the `onError` method in your notification:
399
+
400
+
```php
401
+
public function toTelegram($notifiable)
402
+
{
403
+
return TelegramMessage::create()
404
+
->content('Hello!')
405
+
->onError(function ($data) {
406
+
\Log::error('Failed to send Telegram notification', [
407
+
'chat_id' => $data['to'],
408
+
'error' => $data['exception']->getMessage()
409
+
]);
410
+
});
411
+
}
412
+
```
413
+
414
+
In both methods, the `$data` array contains the following keys:
415
+
416
+
-`to`: The recipient's chat ID.
417
+
-`request`: The payload sent to the Telegram Bot API.
418
+
-`exception`: The exception object containing error details.
419
+
358
420
### On-Demand Notifications
359
421
360
422
> Sometimes you may need to send a notification to someone who is not stored as a "user" of your application. Using the `Notification::route` method, you may specify ad-hoc notification routing information before sending the notification. For more details, you can check out the [on-demand notifications][link-on-demand-notifications] docs.
@@ -386,61 +448,78 @@ Notification::send($recipients, new InvoicePaid());
386
448
387
449
## Available Methods
388
450
389
-
### Shared Methods
451
+
For more information on supported parameters, check out these [docs](https://core.telegram.org/bots/api#sendmessage).
390
452
391
-
> These methods are optional and shared across all the API methods.
453
+
### Common Methods
392
454
393
-
-`to(int|string $chatId)`: Recipient's chat id.
394
-
-`token(string $token)`: Bot token if you wish to override the default token for a specific notification.
395
-
-`button(string $text, string $url, int $columns = 2)`: Adds an inline "Call to Action" button. You can add as many as you want, and they'll be placed 2 in a row by default.
396
-
-`buttonWithCallback(string $text, string $callback_data, int $columns = 2)`: Adds an inline button with the given callback data. You can add as many as you want, and they'll be placed 2 in a row by default.
397
-
-`buttonWithWebApp(string $text, string $url, int $columns = 2)`: Adds an inline button that opens a web application when clicked. This button can be used to direct users to a specific web app.
398
-
-`disableNotification(bool $disableNotification = true)`: Send the message silently. Users will receive a notification with no sound.
399
-
-`options(array $options)`: Allows you to add additional params or override the payload.
400
-
-`sendWhen(bool $condition)`: Sets a condition for sending the notification. If the condition is true, the notification will be sent; otherwise, it will not.
401
-
-`onError(Closure $callback)`: Sets a callback function to handle exceptions. Callback receives an array with `to`, `request`, `exception` keys.
402
-
-`getPayloadValue(string $key)`: Get payload value for given key.
455
+
> These methods are optional and common across all the API methods.
403
456
404
-
### Telegram Message methods
457
+
-`to(int|string $chatId)` - Set recipient's chat ID.
-`parseMode(enum ParseMode $mode)` - Set message parse mode (or `normal()` to unset). Default is `ParseMode::Markdown`.
460
+
-`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.
-`sendWhen(bool $condition)` - Set condition for sending. If the condition is true, the notification will be sent; otherwise, it will not.
467
+
-`onError(Closure $callback)` - Set error handler (receives a data array with `to`, `request`, `exception` keys).
468
+
-`getPayloadValue(string $key)` - Get specific payload value.
405
469
406
-
For more information on supported parameters, check out these [docs](https://core.telegram.org/bots/api#sendmessage).
470
+
### Telegram Message Methods
471
+
472
+
Telegram message notifications are used to send text messages to the user. Supports [Telegram formatting options](https://core.telegram.org/bots/api#formatting-options)
473
+
474
+
-`content(string $content, int $limit = null)` - Set message content with optional length limit. Supports markdown.
475
+
-`line(string $content)` - Add new line of content.
476
+
-`lineIf(bool $condition, string $content)` - Conditionally add new line.
477
+
-`escapedLine(string $content)` - Add escaped content line (for Markdown).
478
+
-`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.
479
+
-`chunk(int $limit = 4096)` - Split long messages (rate limited to 1/second).
480
+
481
+
> **Note:** Chunked messages will be rate limited to one message per second to comply with rate limitation requirements from Telegram.
482
+
483
+
### Telegram Location Methods
484
+
485
+
Telegram location messages are used to share a geographical location with the user.
486
+
487
+
-`latitude(float|string $latitude)` - Set location latitude.
488
+
-`longitude(float|string $longitude)` - Set location longitude.
489
+
490
+
### Telegram File Methods
491
+
492
+
Telegram file messages are used to share various types of files with the user.
407
493
408
-
-`content(string $content, int $limit = null)`: Notification message, supports markdown. For more information on supported markdown styles, check out these [docs](https://core.telegram.org/bots/api#formatting-options).
409
-
-`line(string $content)`: Adds a message in a new line.
410
-
-`lineIf(bool $boolean, string $line)`: Adds a message in a new line if the given condition is true.
411
-
-`escapedLine(string $content)`: Adds a message in a new line while escaping special characters (For Markdown).
412
-
-`view(string $view, array $data = [], array $mergeData = [])`: (optional) Blade template name with Telegram supported HTML or Markdown syntax content if you wish to use a view file instead of the `content()` method.
413
-
-`chunk(int $limit = 4096)`: (optional) Message chars chunk size to send in parts (For long messages). Note: Chunked messages will be rate limited to one message per second to comply with rate limitation requirements from Telegram.
494
+
-`content(string $content)` - Set file caption. Supports markdown.
495
+
-`view(string $view, array $data = [], array $mergeData = [])` - Use Blade template for caption.
496
+
-`file(string|resource|StreamInterface $file, string $type, string $filename = null)` - Attach file by path/URL. Types: `photo`, `audio`, `document`, `video`, `animation`, `voice`, `video_note`. Use helper methods below for convenience. Filename is optional, ex: `sample.pdf`.
414
497
415
-
###Telegram Location methods
498
+
#### Helper Methods:
416
499
417
-
-`latitude(float|string $latitude)`: Latitude of the location.
418
-
-`longitude(float|string $longitude)`: Longitude of the location.
500
+
-`photo(string $file)` - Send photo.
501
+
-`audio(string $file)` - Send audio (MP3).
502
+
-`document(string $file, string $filename = null)` - Send document or any file as document.
-`videoNote(string $file)` - Send video note (≤1min, rounded square video).
419
507
420
-
### Telegram File methods
508
+
### Telegram Contact Methods
421
509
422
-
-`content(string $content)`: (optional) File caption, supports markdown. For more information on supported markdown styles, check out these [docs](https://core.telegram.org/bots/api#formatting-options).
423
-
-`view(string $view, array $data = [], array $mergeData = [])`: (optional) Blade template name with Telegram supported HTML or Markdown syntax content if you wish to use a view file instead of the `content()` method.
424
-
-`file(string|resource|StreamInterface $file, string $type, string $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.
425
-
-`photo(string $file)`: Helper method to attach a photo.
426
-
-`audio(string $file)`: Helper method to attach an audio file (MP3 file).
427
-
-`document(string $file, string $filename = null)`: Helper method to attach a document or any file as document.
428
-
-`video(string $file)`: Helper method to attach a video file.
429
-
-`animation(string $file)`: Helper method to attach an animated gif file.
430
-
-`voice(string $file)`: Helper method to attach a voice note (`.ogg` file with OPUS encoded).
431
-
-`videoNote(string $file)`: Helper method to attach a video note file (Upto 1 min long, rounded square video).
510
+
Telegram contact messages are used to share contact information with the user.
432
511
433
-
### Telegram Contact methods
512
+
-`phoneNumber(string $phone)` - Set contact phone.
513
+
-`firstName(string $name)` - Set contact first name.
514
+
-`lastName(string $name)` - Set contact last name (optional).
515
+
-`vCard(string $vcard)` - Set contact vCard (optional).
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.
441
520
442
-
-`question(string $question)`: Poll question.
443
-
-`choices(array $choices)`: Poll choices.
521
+
-`question(string $question)` - Set poll question.
522
+
-`choices(array $choices)` - Set poll choices.
444
523
445
524
## Alternatives
446
525
@@ -485,7 +564,7 @@ The MIT License (MIT). Please see [License File](LICENSE.md) for more informatio
0 commit comments