README

此包通过 Laravel 使用 Telegram Bot API 发送 Telegram 通知变得非常容易。

内容

安装
用法
可用方法
替代方案
变更日志
测试
安全
贡献
致谢
许可证

安装

您可以通过 composer 安装此包

composer require laravel-notification-channels/telegram

设置您的 Telegram 机器人

与 @BotFather 聊天并生成一个机器人 API 令牌。

然后，配置您的 Telegram 机器人 API 令牌

# config/services.php

'telegram-bot-api' => [
    'token' => env('TELEGRAM_BOT_TOKEN', 'YOUR BOT TOKEN HERE')
],

获取聊天 ID

为了将通知发送到您的 Telegram 机器人用户/频道或群组，我们需要知道它们的聊天 ID。

这可以通过使用 Telegram 机器人 API 的 getUpdates 方法获取您的机器人更新来完成，如 Telegram 机器人 API 文档中所述。

一个更新是一个包含相关字段的对象，这些字段基于它所代表的更新类型，一些更新对象的示例是 message、callback_query 和 poll。有关字段列表的完整列表，请参阅 Telegram 机器人 API 文档。

为了使事情变得简单，该库提供了一个方便的方法，可以用来获取更新，并从中解析相关的聊天 ID。

请注意，用户必须首先与您的机器人互动，您才能获取他们的聊天 ID，然后您可以将该聊天 ID 存储在数据库中，以便将来进行交互或通知。

以下是一个获取更新的示例

use NotificationChannels\Telegram\TelegramUpdates;

// Response is an array of updates.
$updates = TelegramUpdates::create()
    // (Optional). Get's the latest update. NOTE: All previous updates will be forgotten using this method.
    // ->latest()
    
    // (Optional). Limit to 2 updates (By default, updates starting with the earliest unconfirmed update are returned).
    ->limit(2)
    
    // (Optional). Add more params to the request.
    ->options([
        'timeout' => 0,
    ])
    ->get();

if($updates['ok']) {
    // Chat ID
    $chatId = $updates['result'][0]['message']['chat']['id'];
}

注意：如果已设置传出 webhook，则此方法将不起作用。

有关 options 的完整参数列表，请参阅 Telegram 机器人 API 文档。

在 Lumen 中使用

如果您在使用 Lumen 项目中的此通知渠道，您必须在您的 bootstrap/app.php 文件中添加以下代码。

# bootstrap/app.php

// Make sure to create a "config/services.php" file and add the config from the above step.
$app->configure('services');

# Register the notification service providers.
$app->register(Illuminate\Notifications\NotificationServiceProvider::class);
$app->register(NotificationChannels\Telegram\TelegramServiceProvider::class);

代理或网桥支持

如果您无法在您的国家访问 Telegram 机器人 API，您可以通过以下方式设置代理：请参阅此处的说明，或者通过设置上述 base_uri 配置中的网桥 URI 来使用网桥。

您可以在 .env 文件中设置 HTTPS_PROXY。

用法

现在您可以在通知类中的 via() 方法中使用该频道。

文本通知

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

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

    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!")
            ->line("Your invoice has been *PAID*")
            ->lineIf($notifiable->amount > 0, "Amount paid: {$notifiable->amount}")
            ->line("Thank you!")

            // (Optional) Blade template for the content.
            // ->view('notification', ['url' => $url])

            // (Optional) Inline Buttons
            ->button('View Invoice', $url)
            ->button('Download Invoice', $url)
            // (Optional) Inline Button with callback. You can handle callback in your bot instance
            ->buttonWithCallback('Confirm', 'confirm_invoice ' . $this->invoice->id);
    }
}

以下是上述通知在 Telegram 消息中的应用截图预览

使用键盘发送

public function toTelegram($notifiable)
{
    return TelegramPoll::create()
        ->to($notifiable)
        ->content('Choose an option:')
        ->keyboard('Button 1')
        ->keyboard('Button 2');
        // ->keyboard('send your number', request_contact: true)
        // ->keyboard('send your location', request_location: true);
}

预览

发送投票

public function toTelegram($notifiable)
{
    return TelegramPoll::create()
        ->to($notifiable)
        ->question("Aren't Laravel Notification Channels awesome?")
        ->choices(['Yes', 'YEs', 'YES']);
}

预览

附加联系人

public function toTelegram($notifiable)
{
    return TelegramContact::create()
            ->to($notifiable->telegram_user_id) // Optional
            ->firstName('John')
            ->lastName('Doe') // Optional
            ->phoneNumber('00000000');
}

预览

附加音频

public function toTelegram($notifiable)
{
    return TelegramFile::create()
            ->to($notifiable->telegram_user_id) // Optional
            ->content('Audio') // Optional Caption
            ->audio('/path/to/audio.mp3');
}

预览

附加照片

public function toTelegram($notifiable)
{
    return TelegramFile::create()
        ->to($notifiable->telegram_user_id) // Optional
        ->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.github.io/uploads/2017/10/file_example_JPG_1MB.jpg');
}

预览

附加文档

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

预览

附加位置

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

预览

附加视频

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

预览

附加 GIF 文件

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');
}

预览

路由消息

您可以通过向 to($chatId) 方法提供收件人的聊天 ID 来发送通知，如前面的示例所示，或者向您的可通知模型添加一个 routeNotificationForTelegram() 方法。

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

处理响应

您可以使用通知事件来处理来自Telegram的响应。成功时，您的监听器将接收到一个包含各种字段的Message对象，这些字段适合通知类型。

关于响应字段的完整列表，请参阅Telegram Bot API的Message对象文档。

按需通知

有时您可能需要向不是您应用程序“用户”的人发送通知。使用Notification::route方法，在发送通知之前可以指定临时通知路由信息。有关更多详细信息，请参阅按需通知文档。

use Illuminate\Support\Facades\Notification;

Notification::route('telegram', 'TELEGRAM_CHAT_ID')
            ->notify(new InvoicePaid($invoice));

发送给多个收件人

使用通知外观，您可以一次性向多个接收者发送通知。

如果您正在向多个用户发送批量通知，Telegram Bot API将不允许每秒发送超过30条消息。为了获得最佳效果，请考虑在8-12小时的大间隔内分散发送通知。

请注意，您的机器人每分钟不能向同一个群组发送超过20条消息。

如果您超出限制，您将开始收到429错误。有关更多详细信息，请参阅Telegram Bots的常见问题解答。

use Illuminate\Support\Facades\Notification;

// Recipients can be an array of chat IDs or collection of notifiable entities.
Notification::send($recipients, new InvoicePaid());

可用方法

共享方法

这些方法是可选的，并跨所有API方法共享。

to(int|string $chatId)：接收者的聊天id。
token(string $token)：如果您希望为特定通知覆盖默认令牌，则可以指定Bot令牌。
button(string $text, string $url, int $columns = 2)：添加一个内联“操作”按钮。您可以添加任意多个，默认情况下它们将每行放置2个。
buttonWithCallback(string $text, string $callback_data, int $columns = 2)：添加一个带有给定回调数据的内联按钮。您可以添加任意多个，默认情况下它们将每行放置2个。
disableNotification(bool $disableNotification = true)：以静默方式发送消息。用户将收到没有声音的通知。
options(array $options)：允许您添加额外的参数或覆盖负载。
getPayloadValue(string $key)：获取给定键的负载值。

Telegram 消息方法

有关支持的参数的更多信息，请参阅这些文档。

content(string $content, int $limit = null)：通知消息，支持Markdown。有关支持的Markdown样式信息，请参阅这些文档。
line(string $content)：添加一条新行消息。
lineIf(bool $boolean, string $line)：如果给定条件为真，则添加一条新行消息。
escapedLine(string $content)：在Markdown中添加一条新行消息，同时转义特殊字符。
view(string $view, array $data = [], array $mergeData = [])：（可选）如果您想使用视图文件而不是content()方法，则带有Telegram支持HTML或Markdown语法内容的Blade模板名称。
chunk(int $limit = 4096)：（可选）发送消息时按部分发送的字符块大小（用于长消息）。注意：分块消息将被限制为每秒一条消息，以符合Telegram的速率限制要求。

Telegram 位置方法

latitude(float|string $latitude)：位置的纬度。
longitude(float|string $longitude)：位置的经度。

Telegram 文件方法

content(string $content)：（可选）文件标题，支持Markdown。有关支持的Markdown样式信息，请参阅这些文档。
view(string $view, array $data = [], array $mergeData = [])：（可选）如果您想使用视图文件而不是content()方法，则带有Telegram支持HTML或Markdown语法内容的Blade模板名称。
file(string|resource|StreamInterface $file, string $type, string $filename = null): 本地文件路径或远程URL，文件的类型 $type（例如：photo、audio、document、video、animation、voice、video_note）和可选的带扩展名的文件名。例如：sample.pdf。您可以使用辅助方法而不是使用此方法来简化文件附件的处理。
photo(string $file): 附加照片的辅助方法。
audio(string $file): 附加音频文件（MP3文件）的辅助方法。
document(string $file, string $filename = null): 附加文档或任何文件的辅助方法。
video(string $file): 附加视频文件的辅助方法。
animation(string $file): 附加动画GIF文件的辅助方法。
voice(string $file): 附加语音笔记（.ogg文件，OPUS编码）的辅助方法。
videoNote(string $file): 附加视频笔记文件（最长1分钟，方形视频）的辅助方法。

Telegram 联系人方法

phoneNumber(string $phoneNumber): 联系电话号码。
firstName(string $firstName): 联系人名。
lastName(string $lastName): （可选）联系人姓氏。
vCard(string $vCard): （可选）联系人vCard。

Telegram 投票方法

question(string $question): 投票问题。
choices(array $choices): 投票选项。

替代方案

对于高级使用，请考虑使用 telegram-bot-sdk。

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

测试

$ composer test

安全

如果您发现任何安全相关的问题，请通过电子邮件 syed@lukonet.com 而不是使用问题跟踪器。

hamasakibrain / telegram

维护者

详情