README

PHP Telegram Bot

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

目录

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

简介

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

Telegram宣布正式支持机器人API，允许各种集成者将自动化交互引入移动平台。此机器人旨在提供一个平台，用户可以轻松编写机器人并在几分钟内进行交互。

机器人可以

• 使用webhook和getUpdates方法检索更新。
• 支持根据Telegram机器人API 4.9（2020年6月）的所有类型和方法。
• 支持超级群组。
• 处理与其他机器人的聊天中的命令。
• 从机器人管理员界面管理频道。
• 完全支持<强>内联机器人。
• 内联键盘。
• 消息、内联查询和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. 输入（或选择）禁用以让您的机器人接收发送到群组的所有消息。

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": ">=5.5",
        "longman/telegram-bot": "*"
    }
}

然后运行 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 已设置。

现在，创建包含以下内容的 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,
    ]
);

您还可以从与机器人的私密聊天中向用户广播消息。请参阅下方的管理员命令。

筛选更新

可以通过定义自定义更新过滤器来允许或拒绝更新处理。假设我们只想允许ID为428的用户发送消息，我们可以在处理请求之前做以下操作

$telegram->setUpdateFilter(function (Update $update, Telegram $telegram, &$reason = 'Update denied by update_filter') {
    $user_id = $update->getMessage()->getFrom()->getId();
    if ($user_id === 428) {
        return true;
    }

    $reason = "Invalid user with ID {$user_id}";
    return false;
});

使用$reason参数可以定义拒绝更新的原因。此文本将被写入调试日志。

工具

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存储库的进度）。

使用此库的项目

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

• Inline Games (@inlinegamesbot)
• Super-Dice-Roll (@superdiceroll_bot)
• tg-mentioned-bot
• OSMdeWikiBot (@OSM_de)

故障排除

如果您喜欢走在前沿，请向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合作，为您的应用程序构建时使用的开源依赖项提供商业支持和维护。节省时间，降低风险，并提高代码质量，同时为确切依赖项的维护者付费。 了解更多信息。

许可

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

鸣谢

在CREDITS中列出致谢名单