README

基于官方 Telegram Bot API 的 Telegram Bot

简介

这是一个纯 PHP Telegram Bot，完全可以通过插件进行扩展。Telegram 最近宣布官方支持 Bot API，允许各种集成商将自动化交互带到移动平台。此 Bot 的目标是提供一个平台，只需编写一个插件，就可以在几分钟内进行交互。该 Bot 可以

• 使用 webhook 和 getUpdate 方法检索更新。
• 支持 Telegram API 中所有类型和方法（截至 2015 年 10 月 8 日）。
• 处理与其他机器人聊天中的命令。

它已准备好支持频道。

说明

创建您的第一个机器人

1. 向 @botfather 发送消息 https://telegram.me/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 回复

   完成！恭喜您的机器人。您可以在 telegram.me/telesample_bot 找到它。您现在可以为您的机器人添加描述、关于部分和头像，查看 /help 以获取命令列表。

   使用此令牌访问 HTTP API：123456789:AAG90e14-0f8-40183D-18491dDE

   有关 Bot API 的说明，请参阅此页面： https://core.telegram.org/bots/api

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

8. 向 @botfather 输入 /setprivacy。

   

9. @botfather 回复：Choose a bot to change group messages settings.

10. 输入 @telesample_bot（将步骤 5 中设置的名称改为用户名，但以 @ 开头）

11. @botfather 回复

    “启用” - 您的机器人将只接收以 '/' 符号开头或提及机器人用户名的消息。 “禁用” - 您的机器人将接收所有发送到群组的消息。当前状态是：已启用

12. 输入 Disable 以让您的机器人接收所有发送到群组的消息。这一步取决于您。

13. @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.4.0",
        "longman/telegram-bot": "*"
    }
}

然后运行 composer update

或者 在命令行中运行命令

composer require longman/telegram-bot

选择如何获取 Telegram 更新

机器人可以通过 webhook 或 getUpdate 方法处理更新。

Webhook 安装

您需要一个支持 https 和 composer 的服务器。您必须设置 WebHook。创建 set.php（只需编辑 example-set.php）并将其放入其中

<?php
//Composer Loader
$loader = require __DIR__.'/vendor/autoload.php';

$API_KEY = 'your_bot_api_key';
$BOT_NAME = 'namebot';
$link = 'https://yourdomain/yourpath_to_hook.php';
try {
    // create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);
    // set webhook
    $result = $telegram->setWebHook($link);
    if ($result->isOk()) {
        echo $result->getDescription();
    }
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    echo $e;
}

然后通过浏览器打开您的 set.php。

之后，创建 hook.php（或直接编辑 example-hook.php）并将以下内容放入

<?php
$loader = require __DIR__.'/vendor/autoload.php';

$API_KEY = 'your_bot_api_key';
$BOT_NAME = 'namebot';

try {
    // create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);

    // handle telegram webhook request
    $telegram->handle();
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    // log telegram errors
    // echo $e;
}

### 自签名证书 为了上传证书，请在 set.php 中添加证书路径作为参数

$result = $telegram->setWebHook($url, $certificate_path);

获取更新安装

需要MySQL数据库处于激活状态。

创建 getUpdateCLI.php（只需编辑 example-getUpdateCLI.php）并将其放入其中

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

$API_KEY = 'your_bot_api_key';
$BOT_NAME = 'namebot';
$credentials = array('host'=>'localhost', 'user'=>'dbuser', 'password'=>'dbpass', 'database'=>'dbname');

try {
    // create Telegram API object
    $telegram = new Longman\TelegramBot\Telegram($API_KEY, $BOT_NAME);
    $telegram->enableMySQL($credentials);
    // handle telegram getUpdate request
    $telegram->handleGetUpdates();
} catch (Longman\TelegramBot\Exception\TelegramException $e) {
    // log telegram errors
     echo $e;
}                

给予该文件执行权限

chmod 775 getUpdateCLI.php

然后运行

./getUpdateCLI.php

类型

所有类型均按照Telegram API（2015年10月8日）实现。

方法 新增！

所有方法均按照Telegram API（2015年10月8日）实现。### 发送照片 为了发送本地照片，请将文件路径作为第二个参数提供

$data['chat_id'] = $chat_id;
$result = Request::sendPhoto($data,$this->telegram->getUploadPath().'/'.'image.jpg');

如果您知道之前上传文件的file_id，只需在第一个参数中提供即可

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

sendAudio、sendDocument、sendSticker、sendVideo 和 sendVoice 的使用方式相同。有关完整示例，请参阅 ImageCommand.php。### 发送聊天动作

Request::sendChatAction(['chat_id' => $chat_id, 'action' => 'typing']);

### 获取用户个人资料照片 获取用户照片，有关完整示例，请参阅 WhoamiCommand.php。

### 获取文件和下载文件 获取文件路径并下载，有关完整示例，请参阅 WhoamiCommand.php。

向所有活跃聊天发送消息

为此，您必须启用MySQL连接。以下是一个使用示例

$results = $telegram->sendToActiveChats(
        'sendMessage', //callback function to execute (see Request.php methods)
        array('text'=>'Hey! Checkout the new feature!!'), //Param to evaluate the request
        true, //Send to chats (group chat)
        true, //Send to users (single chat)
        null, //'yyyy-mm-dd hh:mm:ss' date range from
        null  //'yyyy-mm-dd hh:mm:ss' date range to
    );

工具

MySQL存储（推荐）

如果您想将消息/用户/聊天插入数据库以供后续在命令中使用，请创建数据库并导入 structure.sql，在对象创建后和 handle 方法之前启用MySQL支持

$credentials = array('host'=>'localhost', 'user'=>'dbuser',
'password'=>'dbpass', 'database'=>'dbname');

$telegram->enableMySQL($credentials);

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

$telegram->enableMySQL($credentials, $BOT_NAME.'_');

命令

该机器人能够识别带有多个机器人（/command@mybot）的聊天中的命令。它可以通过触发聊天事件来执行命令。以下是列表

• 群聊创建（GroupchatcreatedCommand.php）
• 新聊天参与者（NewchatparticipantCommand.php）
• 删除聊天照片（DeletechatphotoCommand.php）
• 新聊天标题（NewchattitleCommand.php）
• 离开聊天参与者（LeftchatparticipantCommand.php）

GenericCommand.php 允许您处理不存在的命令或使用命令作为变量：最喜欢的颜色？ /black, /red 最喜欢的数字？ /1, /134

GenericmessageCommand.php 允许您处理任何类型的消息。

您可能希望开发自己的命令。一个好的做法是将它们存储在 vendor/ 之外。可以通过添加方法来实现这一点

$COMMANDS_FOLDER = __DIR__.'/Commands/';
$telegram->addCommandsPath($COMMANDS_FOLDER);

在 CommandsExamples/ 中有一些示例，展示了如何使用类型。

管理员命令

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

• 向所有聊天发送消息
• 列出由机器人启动的所有聊天（新增！）

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

$telegram->enableAdmins(array('TelegramUserID','Othersid'));

您可以使用命令 /whoami 获取Telegram用户ID。管理员命令存储在 src/Admin/ 文件夹中。要了解所有可用的命令，请输入 /help。

命令配置

使用此方法，您可以设置一些命令特定的参数，例如，日期命令的google geocode/timezone API密钥

$telegram->setCommandConfig('date',
array('google_api_key'=>'your_google_api_key_here'));

上传和下载目录

您可以使用以下方式覆盖默认的上传和下载目录

$telegram->setDownloadPath("yourpath/Download");
$telegram->setUploadPath("yourpath../Upload");    

日志记录

抛出的异常存储在 TelegramException.log 文件中（在基本目录中）。

传入的更新（来自webhook和getUpdates的json字符串）可以通过以下方法记录在文本文件中

$telegram->setLogRequests(true);
$telegram->setLogPath($BOT_NAME.'.log');

（新增！）将详细程度设置为3，以记录curl请求和机器人对Telegram的响应

$telegram->setLogRequests(true);
$telegram->setLogPath($BOT_NAME.'.log');
$telegram->setLogVerbosity(3);     

此代码可在 Github 上找到。欢迎提交pull requests。

故障排除

如果您喜欢生活在边缘，请将您发现的任何错误报告到PHP Telegram Bot问题页面。

贡献

有关信息，请参阅CONTRIBUTING.md。

致谢

致谢列表请参阅CREDITS。