README

为 Telegram Bot API PHP SDK 扩展，允许在机器人中实现对话

此库允许为您的 Telegram 机器人创建简单的对话，这些对话基于Telegram Bot SDK。

安装

您可以使用 Composer 轻松安装此包

composer require okaufmann/telegram-bot-dialogs

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="BotDialogs\DialogsServiceProvider" --tag="config"

每个对话都应该实现为一个扩展基本 Dialog 的类，如下面的示例所示

use BotDialogs\Dialog;

class HelloDialog extends Dialog
{
    // Array with methods that contains logic of dialog steps.
    // The order in this array defines the sequence of execution.
    protected $steps = ['hello', 'fine', 'bye'];

    public function hello()
    {
        $this->telegram->sendMessage([
            'chat_id' => $this->getChat()->getId(),
            'text' => 'Hello! How are you?'
        ]);
    }

    public function bye()
    {
        $this->telegram->sendMessage([
            'chat_id' => $this->getChat()->getId(),
            'text' => 'Bye!'
        ]);
        $this->jump('hello');
    }

    public function fine()
    {
        $this->telegram->sendMessage([
            'chat_id' => $this->getChat()->getId(),
            'text' => 'I\'m OK :)'
        ]);
    }
}

为了初始化新的对话，您必须使用 Dialogs 类实例添加新的对话实现。并且为了执行第一个和后续步骤，您必须使用带有更新对象的 Dialogs::proceed() 方法。此外，还可以使用类型提示通过 DI 使用对话。

use Telegram\Bot\Commands\Command;
use BotDialogs\Dialogs;
use App\Dialogs\HelloDialog;

class HelloCommand extends Command
{
    protected $name = 'hello';

    protected $description = 'Just say "Hello" and ask few questions';

    public function __construct(Dialogs $dialogs)
    {
        $this->dialogs = $dialogs;
    }

    public function handle($arguments)
    {
        $this->dialogs->add(new HelloDialog($this->update));
    }
}

在 webhook 控制器中的代码

use Telegram\Bot\Api;
use BotDialogs\Dialogs;

// ...

public function __construct(Api $telegram, Dialogs $dialogs)
{
  $this->telegram = $telegram;
  $this->dialogs = $dialogs;
}

// ...

$update = $this->telegram->commandsHandler(true);

if (!$this->dialogs->exists($update)) {
  // Do something if there are no existing dialogs
} else {
  // Call the next step of the dialog
  $this->dialogs->proceed($update);
}

使用 Redis 存储对话信息（也用于 Dialog::remember() 方法推送的数据）。

高级定义对话步骤

您可以为您的对话步骤定义默认文本回答。为此，您必须将步骤定义为包含名称和响应字段的数组。

class HelloDialog extends Dialog
{
    protected $steps = [
        [
            'name' => 'hello',
            'response' => 'Hello my friend!'
        ],
        'fine',
        'bye'
    ];

    // ...
}

在这种情况下，如果您不需要步骤处理程序中的任何逻辑，则不需要定义它。只需将响应放在步骤定义中即可。这对于欢迎信息、提示/建议信息等效果很好。如果想要使用 markdown 格式化响应，只需将 markdown 字段设置为 true。

此外，您可以在步骤中通过定义 jump 和 end 字段来控制对话方向。jump 作用类似于 jump() 方法 - 对话跳转到特定步骤。end 字段，设置为 true，在当前步骤后结束对话。

此外，您还可以使用步骤的 is_dich（是否为二分问题）选项。如果此选项设置为 true，则可以使用 Dialog 实例的 yes 和 no 字段来检查用户答案。例如

class HelloDialog extends Dialog
{
    protected $steps = [
        [
            'name' => 'hello',
            'response' => 'Hello my friend! Are you OK?'
        ],
        [
            'name' => 'answer',
            'is_dich' => true
        ],
        'bye'
    ];

    public function answer()
    {
        if ($this->yes) {
            // Send message "I am fine, thank you!"
        } elseif ($this->no) {
            // Send message "No, I am got a sick :("
        }
    }
}

在 config/dialogs.php 中，您可以修改 yes/no 的别称。

在二分问题中，通常只需要发送响应并跳转到另一个步骤。在这种情况下，您可以定义带有响应的步骤，并将它们的名称设置为二分步骤的 'yes'、'no' 或 'default' 键的值。例如

class HelloDialog extends Dialog
{
    protected $steps = [
        [
            'name' => 'hello',
            'response' => 'Hello my friend! Are you OK?'
        ],
        [
            'name' => 'answer',
            'is_dich' => true,
            'yes' => 'fine',
            'no' => 'sick',
            'default' => 'bye'
        ],
        [
            'name' => 'fine',
            'response' => 'I am fine, thank you!',
            'jump' => 'bye',
        ],
        [
            'name' => 'sick',
            'response' => 'No, I am got a sick :(',
        ],
        'bye'
    ];
}

在对话中进行访问控制

您可以通过继承 AuthorizedDialog 类并将 Telegram 用户名放入 $allowedUsers 属性中来执行访问控制。然后只需允许列表中的用户启动对话。

Dialog 类的可用方法

start() - 从第一个步骤开始对话
proceed() - 将对话推进到下一个步骤
end() - 结束对话
jump($step) - 跳转到特定步骤
remember($value) - 为下一步使用记住一些信息（目前只支持“短时”记忆，仅用于一步操作）
isEnd() - 检查对话是否结束

Dialogs 类的可用方法

add(Dialog $dialog) - 添加新的对话
get(Telegram\Bot\Objects\Update $update) - 返回现有对话的对象
proceed(Telegram\Bot\Objects\Update $update) - 运行现有对话的下一步处理程序
exists(Telegram\Bot\Objects\Update $update) - 检查是否存在现有对话

在单独的文件中配置步骤

您可以在单独的 yaml 或 php 文件中定义对话配置。为此，在对话配置文件中设置 scenarios，使用对话类名作为键，配置文件的路径作为值，例如

'scenarios' => [
        HelloDialog::class => base_path('config/dialogs/hello.yml')
],

生产环境中存储在默认缓存实例中的文件配置。因此，您应在部署脚本中添加 php artisan cache:clear。

okaufmann / telegram-bot-dialogs

维护者

详细信息