README

PHP Telegram Bot

基于官方 Telegram Bot API 的 Telegram 机器人

仅支持 PHP > v7.4 PSR-12

目录

• 介绍
• 说明
  • 创建您的第一个机器人
  • 使用 Composer 安装此包
  • 选择如何检索 Telegram 更新
• Webhook 安装
  • 自签名证书
  • 取消设置 Webhook
• getUpdates 安装
  • 无数据库的 getUpdates
• 支持
  • 类型
  • 内联查询
  • 方法
  • 发送消息
  • 发送图片
  • 发送聊天动作
  • getUserProfilePhoto
  • getFile 和 downloadFile
  • 向所有活跃聊天发送消息
• 工具
  • MySQL 存储（推荐）
    • 外部数据库连接
  • 频道支持
• 命令
  • 预定义命令
  • 自定义命令
  • 命令配置
  • 管理员命令
    • 设置管理员
    • 频道管理
• 上传和下载目录路径
• 日志记录
• 文档
• 资产
• 示例机器人
• 使用此库的项目
• 故障排除
• 贡献
• 安全
• 捐赠
• 企业
• 许可
• 致谢

介绍

这是一个纯 PHP Telegram 机器人，可以通过插件完全扩展。

Telegram 宣布了对 Bot API 的官方支持，允许各种集成商将自动化交互引入移动平台。这个机器人旨在提供一个平台，用户可以简单地编写一个机器人，并在几分钟内完成交互。

该机器人可以

• 通过 webhook 和 getUpdates 方法检索更新。
• 支持根据 Telegram API 4.4（2019 年 7 月）的所有类型和方法。
• 支持超级群组。
• 处理与其他机器人在聊天中的命令。
• 从机器人管理员界面管理频道。
• 完全支持 内联机器人。
• 内联键盘。
• 消息、InlineQuery 和 ChosenInlineQuery 存储在数据库中。
• 会话功能。

此代码可在 GitHub 上找到。欢迎提交拉取请求。

说明

创建您的第一个机器人

1. 向以下文本的消息 @BotFather： /newbot

   如果您不知道如何通过用户名发送消息，请点击您的 Telegram 应用中的搜索字段并输入 @BotFather，您应该能够开始对话。请小心不要将其发送到错误的联系人，因为一些用户与 BotFather 有类似的用户名。

   

2. @BotFather 会回复

   Alright, a new bot. How are we going to call it? Please choose a name for your bot.
   

3. 键入您想为您的机器人设置的任何名称。

4. @BotFather 会回复

   Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
   

5. 键入您想为您的机器人设置的任何用户名，最小长度为 5 个字符，且必须以 bot 结尾。例如：telesample_bot

6. @BotFather 会回复

   Done! Congratulations on your new bot. You will find it at
   telegram.me/telesample_bot. You can now add a description, about
   section and profile picture for your bot, see /help for a list of
   commands.
   
   Use this token to access the HTTP API:
   123456789:AAG90e14-0f8-40183D-18491dDE
   
   For a description of the Bot API, see this page:
   https://core.telegram.org/bots/api
   

7. 记下上面提到的 'token'。

可选设置机器人隐私

1. 向 @BotFather 发送 /setprivacy

   

2. @BotFather 会回复

   Choose a bot to change group messages settings.
   

3. 键入（或选择）@telesample_bot（更改为您在第 5 步以上设置的名称，但以 @ 开头）

4. @BotFather 会回复

   'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
   'Disable' - your bot will receive all messages that people send to groups.
   Current status is: ENABLED
   

5. 键入（或选择）Disable 以让您的机器人接收发送到群组的所有消息。

6. @BotFather 会回复

   Success! The new status is: DISABLED. /help
   

使用 Composer 安装此包

通过 Composer 安装此软件包。编辑你的项目 composer.json 文件以要求 longman/telegram-bot。

创建 composer.json 文件

{
    "name": "yourproject/yourproject",
    "type": "project",
    "require": {
        "php": ">=7.4",
        "klevialent/core": "*"
    }
}

然后运行 composer update

或者

在你的命令行中运行以下命令

composer require longman/telegram-bot

选择如何检索 Telegram 更新

该机器人可以通过 Webhook 或 getUpdates 方法处理更新

Webhook 安装

注意：要获取更详细的解释，请访问 example-bot 仓库 并按照那里的说明操作。

为了设置 Webhook，你需要一个支持 HTTPS 和 composer 的服务器。（对于 自签名证书，你需要添加一些额外的代码）

创建包含以下内容的 set.php

<?php
// Load composer
require __DIR__ . '/vendor/autoload.php';

$bot_api_key  = 'your:bot_api_key';
$bot_username = 'username_bot';
$hook_url     = 'https://your-domain/path/to/hook.php';

try {
    // Create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($bot_api_key, $bot_username);

    // Set webhook
    $result = $telegram->setWebhook($hook_url);
    if ($result->isOk()) {
        echo $result->getDescription();
    }
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    // log telegram errors
    // echo $e->getMessage();
}

通过浏览器打开你的 set.php 以将 webhook 注册到 Telegram。你应该会看到 Webhook was set。

现在，创建包含以下内容的 hook.php

<?php
// Load composer
require __DIR__ . '/vendor/autoload.php';

$bot_api_key  = 'your:bot_api_key';
$bot_username = 'username_bot';

try {
    // Create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($bot_api_key, $bot_username);

    // Handle telegram webhook request
    $telegram->handle();
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    // Silence is golden!
    // log telegram errors
    // echo $e->getMessage();
}

自签名证书

为了上传证书，将证书路径作为参数添加到 set.php 中

$result = $telegram->setWebhook($hook_url, ['certificate' => '/path/to/certificate']);

取消设置 Webhook

使用你的机器人凭据编辑 unset.php 并执行它

getUpdates 安装

为了获得最佳性能，MySQL 数据库应该启用 getUpdates 方法！

创建包含以下内容的 getUpdatesCLI.php

#!/usr/bin/env php
<?php
require __DIR__ . '/vendor/autoload.php';

$bot_api_key  = 'your:bot_api_key';
$bot_username = 'username_bot';

$mysql_credentials = [
   'host'     => 'localhost',
   'port'     => 3306, // optional
   'user'     => 'dbuser',
   'password' => 'dbpass',
   'database' => 'dbname',
];

try {
    // Create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($bot_api_key, $bot_username);

    // Enable MySQL
    $telegram->enableMySql($mysql_credentials);

    // Handle telegram getUpdates request
    $telegram->handleGetUpdates();
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    // log telegram errors
    // echo $e->getMessage();
}

接下来，给文件赋予执行权限

$ chmod +x getUpdatesCLI.php

最后，运行它！

$ ./getUpdatesCLI.php

无数据库的 getUpdates

如果你选择使用 getUpdates 方法而不使用数据库，你可以将上面的 $telegram->useMySQL(...); 行替换为

$telegram->useGetUpdatesWithoutDatabase();

支持

类型

所有类型均按照 Telegram API（2016年1月20日）实现。

内联查询

根据 Telegram API（2016年1月20日）全面支持内联查询。

方法

所有方法均按照 Telegram API（2016年1月20日）实现。

发送消息

超过 4096 个字符的消息将被分成多个消息。

$result = Request::sendMessage([
    'chat_id' => $chat_id,
    'text'    => 'Your utf8 text 😜 ...',
]);

发送图片

要发送本地照片，请使用文件路径正确地将它添加到 $data 参数中

$result = Request::sendPhoto([
    'chat_id' => $chat_id,
    'photo'   => Request::encodeFile('/path/to/pic.jpg'),
]);

如果你知道已上传文件的 file_id，只需直接在数据数组中使用它即可

$result = Request::sendPhoto([
    'chat_id' => $chat_id,
    'photo'   => 'AAQCCBNtIhAoAAss4tLEZ3x6HzqVAAqC',
]);

要发送远程照片，请使用直接 URL

$result = Request::sendPhoto([
    'chat_id' => $chat_id,
    'photo'   => 'https://example.com/path/to/pic.jpg',
]);

sendAudio、sendDocument、sendAnimation、sendSticker、sendVideo、sendVoice 和 sendVideoNote 都以相同的方式工作，只需查看 API 文档 以获取确切用法。请参阅 ImageCommand.php 以获取完整示例。

发送聊天动作

Request::sendChatAction([
    'chat_id' => $chat_id,
    'action'  => Longman\TelegramBot\ChatAction::TYPING,
]);

getUserProfilePhoto

检索用户照片，请参阅 WhoamiCommand.php 以获取完整示例。

getFile 和 downloadFile

获取文件路径并下载它，请参阅 WhoamiCommand.php 以获取完整示例。

向所有活跃聊天发送消息

为此，你必须启用 MySQL 连接。以下是一个使用示例（请检查 DB::selectChats() 以了解参数使用）

$results = Request::sendToActiveChats(
    'sendMessage', // Callback function to execute (see Request.php methods)
    ['text' => 'Hey! Check out the new features!!'], // Param to evaluate the request
    [
        'groups'      => true,
        'supergroups' => true,
        'channels'    => false,
        'users'       => true,
    ]
);

你也可以从与你的机器人的私密聊天中向用户广播消息。请查看下面的 管理命令。

工具

MySQL 存储（推荐）

如果您想将消息/用户/聊天保存下来以便在命令中使用，请创建一个新的数据库（utf8mb4_unicode_520_ci），导入structure.sql并在创建对象后、调用handle()方法之前启用MySQL支持。

$mysql_credentials = [
   'host'     => 'localhost',
   'port'     => 3306, // optional
   'user'     => 'dbuser',
   'password' => 'dbpass',
   'database' => 'dbname',
];

$telegram->enableMySql($mysql_credentials);

在启用MySQL的同时，您可以设置所有表的自定义前缀。

$telegram->enableMySql($mysql_credentials, $bot_username . '_');

您还可以将内联查询和选择的内联查询数据存储在数据库中。

外部数据库连接

您可以向库提供外部MySQL PDO连接。以下是配置方法：

$telegram->enableExternalMySql($external_pdo_connection)
//$telegram->enableExternalMySql($external_pdo_connection, $table_prefix)

频道支持

所有实现的方法都可以用于管理频道。通过管理命令，您可以直接使用您的机器人私聊管理频道。

命令

预定义命令

机器人能够识别含有多个机器人的聊天中的命令（/command@mybot）。

它可以执行由聊天事件触发的命令。

以下是一些列表：

• StartCommand.php（新用户开始使用机器人。）

• NewChatMembersCommand.php（新成员被添加到群组，有关他们的信息。）

• LeftChatMemberCommand.php（成员被从群组中移除，有关他们的信息。）

• NewChatTitleCommand.php（聊天标题被更改为此值。）

• NewChatPhotoCommand.php（聊天照片被更改为此值。）

• DeleteChatPhotoCommand.php（服务消息：聊天照片被删除。）

• GroupChatCreatedCommand.php（服务消息：群组已创建。）

• SupergroupChatCreatedCommand.php（服务消息：超级群组已创建。）

• ChannelChatCreatedCommand.php（服务消息：频道已创建。）

• MigrateToChatIdCommand.php（群组已迁移到具有指定标识符的超群组。）

• MigrateFromChatIdCommand.php（超级群组已从具有指定标识符的群组迁移。）

• PinnedMessageCommand.php（指定消息被固定。）

• GenericmessageCommand.php（处理任何类型的消息。）

• GenericCommand.php（处理不存在或作为变量使用的命令。）

  • 最喜欢的颜色？/black, /red
  • 最喜欢的数字？/1, /134

自定义命令

也许您想开发自己的命令。这里有指南帮助您创建自己的命令。

此外，请务必查看示例命令以了解有关自定义命令及其工作方式的更多信息。

命令配置

使用此方法，您可以设置一些特定的命令参数，例如

// Google geocode/timezone API key for /date command
$telegram->setCommandConfig('date', [
    'google_api_key' => 'your_google_api_key_here',
]);

// OpenWeatherMap API key for /weather command
$telegram->setCommandConfig('weather', [
    'owm_api_key' => 'your_owm_api_key_here',
]);

管理员命令

启用此功能后，机器人管理员可以执行一些超级用户命令

• 列出所有以机器人开始的聊天/chats
• 清理旧数据库条目/cleanup
• 显示有关机器人的调试信息/debug
• 向所有聊天发送消息/sendtoall
• 将任何内容发布到您的频道/sendtochannel
• 使用/whois检查用户或聊天

查看存储在src/Commands/AdminCommands/文件夹中的所有默认管理命令。

设置管理员

您可以使用此选项指定一个或多个管理员

// Single admin
$telegram->enableAdmin(your_telegram_user_id);

// Multiple admins
$telegram->enableAdmins([
    your_telegram_user_id,
    other_telegram_user_id,
]);

可以使用/whoami命令检索Telegram用户ID。

频道管理

要启用此功能，请按照以下步骤操作：

• 将您的机器人添加为频道管理员，这可以通过任何Telegram客户端完成。
• 如上所述，为您的用户启用管理界面。
• 将您的频道名称作为/sendtochannel命令的参数输入

$telegram->setCommandConfig('sendtochannel', [
    'your_channel' => [
        '@type_here_your_channel',
    ]
]);

• 如果您想管理更多频道

$telegram->setCommandConfig('sendtochannel', [
    'your_channel' => [
        '@type_here_your_channel',
        '@type_here_another_channel',
        '@and_so_on',
    ]
]);

• 享受吧！

上传和下载目录路径

要使用上传和下载功能，您需要使用以下方法设置路径：

$telegram->setDownloadPath('/your/path/Download');
$telegram->setUploadPath('/your/path/Upload');

文档

请查看Wiki以获取更多信息和使用教程！请随时改进！

资产

所有项目资产都可以在assets仓库中找到。

示例机器人

我们正在忙于创建一个完整的A-Z示例机器人，以帮助您开始使用这个库，并展示如何使用所有功能。您可以检查example-bot仓库的进度。

使用此库的项目

以下是一些使用此库的项目列表，欢迎您添加自己的项目！

• 内联游戏 (@inlinegamesbot)
• 超级骰子 (@superdiceroll_bot)
• tg-mentioned-bot

故障排除

如果您喜欢冒险，请将您在PHP Telegram Bot问题页面上发现的任何错误报告。

贡献

有关更多信息，请参阅CONTRIBUTING。

安全

有关更多信息，请参阅SECURITY。

捐赠

这个机器人的所有工作都是在我们业余时间花费了许多小时编码完成的，以为您提供易于使用和扩展的Telegram Bot库。如果您喜欢使用这个库，并想表示感谢，捐赠是表达您支持的一种很好的方式。

捐赠将重新投入到项目中👍

感谢您使这个项目保持活力🙏

• Patreon.com/phptelegrambot
• OpenCollective.com/php-telegram-bot
• Ko-fi.com/phptelegrambot
• Tidelift.com/longman/telegram-bot
• Liberapay.com/PHP-Telegram-Bot
• PayPal.me/noplanman (账户为@noplanman)
• 166NcyE7nDxkRPWidWtG1rqrNJoD5oYNiV
• 0x485855634fa212b0745375e593fAaf8321A81055

企业

作为Tidelift订阅的一部分提供。

PHP Telegram Bot的维护者以及成千上万的包维护者正在与Tidelift合作，为您的应用程序构建时使用的开源依赖项提供商业支持和维护。节省时间，降低风险，并提高代码质量，同时支付您使用的确切依赖项的维护者。了解更多信息：Learn more.

许可

请参阅此仓库中包含的LICENSE，以获取MIT许可证的完整副本，该项目据此许可。

致谢

在CREDITS中列出致谢名单。