README

基于官方Telegram Bot API的Telegram Bot

介绍

这是一个纯PHP Telegram Bot，可以通过插件完全扩展。Telegram最近宣布正式支持Bot API，允许各种集成商将自动化交互带到移动平台。此Bot旨在提供一个平台，在这里可以简单地编写一个插件，并在几分钟内完成交互。

该Bot可以

通过Webhook和getUpdates方法检索更新。
支持Telegram API（2016年5月25日）中的所有类型和方法。
支持超级群组。
处理与其他bot在聊天中的命令。
从bot管理员界面管理频道。
完全支持内联bot。
内联键盘。
消息、InlineQuery和ChosenInlineQuery存储在数据库中。
Botan.io集成和数据库缓存系统。（新功能）
会话功能

此代码可在Github上找到。欢迎提出pull请求。

说明

创建你的第一个bot

向@botfather https://telegram.me/botfather发送以下文本：/newbot 如果你不知道如何通过用户名发送消息，点击你的Telegram应用中的搜索字段，并输入@botfather，你应该能够开始会话。请小心不要发送给错误的联系人，因为一些用户的用户名与botfather相似。
@botfather回复：Alright, a new bot. How are we going to call it? Please choose a name for your bot.
输入你想要的bot名称。
@botfather回复：Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
输入你想要的bot用户名，至少5个字符，并且必须以bot结尾。例如：telesample_bot

@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

记下上面提到的'token'。
向@botfather输入/setprivacy。
@botfather回复：Choose a bot to change group messages settings.
输入（或选择）@telesample_bot（更改为你在第5步上设置的名称，但以@开头）

@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

输入（或选择）Disable，以便你的bot接收发送到群组的所有消息。这一步实际上取决于你。
@botfather回复：成功！新状态：禁用。/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',
   '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参数中

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

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

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

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

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

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

发送聊天动作

Request::sendChatAction(['chat_id' => $chat_id, 'action' => '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',
   '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)

频道支持

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

Botan.io集成（可选）

您可以使用以下行在您的hook.php中启用集成

$telegram->enableBotan('your_token');

将your_token替换为您的Botan.io令牌，请参阅此页面了解获取令牌的方法。

以下操作将被跟踪

命令（在统计中显示为Command (/command_name)）
行内查询、选择的行内结果和回调查询
发送到机器人的消息（或在群组中的回复）

为了使用URL缩短器，您必须包含类use Longman\TelegramBot\Botan;并以这种方式调用它

Botan::shortenUrl('https://github.com/php-telegram-bot/core', $user_id);

缩短的URL将存储在数据库中（如果已启用MySQL存储）。

命令

预定义命令

机器人能够识别包含多个机器人的聊天中的命令（/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获取更多信息以及教程！欢迎改进！

示例bot

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

使用此库的项目

以下是一些使用该库的项目，欢迎您添加您的项目！

故障排除

如果您喜欢走在前沿，请将您在PHP Telegram Bot issues页面上发现的任何错误报告。

贡献

更多信息请参阅CONTRIBUTING。

捐赠

我们利用业余时间投入了大量时间来编写这个机器人，为您提供一个易于使用和扩展的Telegram Bot库。如果您喜欢使用这个库并想表示感谢，捐款是表达您支持的一种很好的方式。

捐款将回馈到项目中 👍

Gratipay: Gratipay/PHP-Telegram-Bot
Liberapay: Liberapay/PHP-Telegram-Bot
PayPal: PayPal/noplanman（@noplanman的账户）
Bitcoin: 166NcyE7nDxkRPWidWtG1rqrNJoD5oYNiV
Ethereum: 0x485855634fa212b0745375e593fAaf8321A81055

许可

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

致谢

致谢名单请参阅CREDITS。

deflou / longman-telegram-bot

维护者

详细信息