README

用于在 Telegram Bot API PHP SDK 中实现对话的扩展

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

安装

您可以使用 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() 方法。此外，您还可以通过类型提示使用 Telegram 命令和依赖注入。

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。

talanoff / telegram-bot-dialogs

维护者

详细信息