Voiceflousion

Voiceflousion是一个框架，旨在将Voiceflow聊天机器人构建器中的聊天机器人集成到任何聊天平台中。目前，它支持Voiceflow机器人与Telegram和WhatsApp的集成，未来计划还包括Instagram、Discord等。该框架还提供了自己的Web服务器，用于启动聊天机器人，并为任何聊天平台创建自定义集成工具，支持文本、按钮、图片、卡片和轮播图等消息格式。

功能

• Telegram和WhatsApp集成：支持文本、按钮、图片、卡片和轮播图。
• 自定义集成：提供工具，以最少的代码开发任何聊天平台的集成。
• 会话管理：全自动的用户和机器人会话管理（创建、清理、验证、同步保证）。
• 可扩展性：支持单个Voiceflow机器人的多个客户端机器人，以及单个服务器上的多个Voiceflow机器人和客户端。
• 管理功能：创建管理界面的功能，例如检索所有机器人会话、激活和停用用户会话。
• 可扩展性：易于扩展以支持Instagram和WhatsApp等额外平台。
• 多用户支持：客户端机器人支持同时处理多个用户，并提供灵活的最大用户数、会话有效时间和清理间隔设置。
• Voiceflousion服务器：无需外部依赖项即可启动和管理聊天机器人的Web服务器。
• 自定义处理程序：开发者可以编写自定义函数来处理机器人的工作流程，例如将对话部分保存到数据库中。
• 服务器安全性：为Voiceflousion服务器设置机器人身份验证令牌和允许的来源设置。

安装和配置

先决条件

• Rust（最新稳定版本）
• Cargo（Rust包管理器）
• 一个已准备好的Voiceflow机器人，包括其API密钥、机器人ID和版本ID
• 使用相应工具创建的Telegram或WhatsApp机器人，包括其API密钥

环境变量

建议将API密钥等敏感信息存储在.env文件中。以下是.env文件内容的示例

VF_API_KEY=VF.DM.xxxxxxxxxxxx.xxxxxxxxxx
BOT_ID=32487267c832hx4h248
VERSION_ID=27hd634532742g424234
TELEGRAM_BOT_TOKEN=4324234324:xxxxxxxxxxxxxxxx
WHATSAPP_BOT_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WHATSAPP_BOT_ID=xxxxxxxxxxxxxxxxxxxx

快速入门：运行示例项目

克隆仓库

git clone https://github.com/Vondert/voiceflousion.git
cd voiceflousion

导航到示例目录

cd example

将 .env.example 重命名为 .env 并填写所需信息

mv .env.example .env

安装依赖并运行示例

cargo run --release

将 Voiceflousion 添加到您的项目（Telegram 和 WhatsApp）

设置环境

在项目的根目录中创建一个 .env 文件，并填写必要的变量

VF_API_KEY=VF.DM.xxxxxxxxxxxx.xxxxxxxxxx
BOT_ID=32487267c832hx4h248
VERSION_ID=27hd634532742g424234
TELEGRAM_BOT_TOKEN=4324234324:xxxxxxxxxxxxxxxx
WHATSAPP_BOT_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WHATSAPP_BOT_ID=xxxxxxxxxxxxxxxxxxxx

添加依赖

将以下依赖添加到您的 Cargo.toml 文件中

[package]
name = "example"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0.193", features = ["derive"] }
dotenv = "0.15.0"
serde_json = "1.0.114"
tokio = { version = "1.36.0", features = ["rt", "rt-multi-thread", "macros"] }
voiceflousion = { version = "0.3.1", features = ["all-integrations", "server"] }

设置主文件

加载环境变量：使用 dotenv 从 .env 文件中加载环境变量。

use dotenv::dotenv;

dotenv().ok();

检索环境变量：从环境中获取必要的 API 密钥和 ID。

use std::env;

let bot_id: String = env::var("BOT_ID").unwrap_or_else(|_| "".to_string());
let version_id: String = env::var("VERSION_ID").unwrap_or_else(|_| "".to_string());
let vf_api_key: String = env::var("VF_API_KEY").unwrap_or_else(|_| "".to_string());
let telegram_bot_token = env::var("TELEGRAM_BOT_TOKEN").unwrap_or_else(|_| "".to_string());
let telegram_bot_id = telegram_bot_token.split(':').next().unwrap().to_string();
let whatsapp_bot_token = env::var("WHATSAPP_BOT_TOKEN").unwrap_or_else(|_| "".to_string());
let whatsapp_bot_id = env::var("WHATSAPP_BOT_ID").unwrap_or_else(|_| "".to_string());

初始化 Voiceflow 客户端：创建一个新的 VoiceflowClient 实例。

use std::sync::Arc;
use voiceflousion::core::voiceflow::VoiceflowClient;

let voiceflow_client = Arc::new(VoiceflowClient::new(vf_api_key, bot_id.clone(), version_id, 10, None));

构建 Telegram 客户端和 WhatsApp 客户端：使用会话管理设置 TelegramClient 和 WhatsAppClient。

use voiceflousion::core::ClientBuilder;
use voiceflousion::integrations::telegram::TelegramClient;

let client_builder = ClientBuilder::new(telegram_bot_id.clone(), telegram_bot_token.clone(), voiceflow_client.clone(), 10)
    .add_session_duration(120)
    .allow_sessions_cleaning(60);
let telegram_client = Arc::new(TelegramClient::new(client_builder));

let client_builder = ClientBuilder::new(whatsapp_bot_id.clone(), whatsapp_bot_token.clone(), voiceflow_client.clone(), 10)
.set_session_duration(120)
.allow_sessions_cleaning(60);
let whatsapp_client = WhatsAppClient::new(client_builder);

构建 Telegram 客户端和 WhatsApp 客户端管理器：使用创建的客户端设置 ClientManager。

use voiceflousion::core::base_structs::ClientsManager;

let telegram_client_manager = Arc::new(ClientsManager::from_clients(vec![telegram_client]));
let whatsapp_client_manager = Arc::new(ClientsManager::from_clients(vec![whatsapp_client]));

设置 Voiceflousion 服务器：使用先前构建的 ClientManager 实例创建 VoiceflousionServer 并设置处理客户端更新的基本对话处理程序。

use voiceflousion::server::handlers::base_dialog_handler;
use voiceflousion::server::VoiceflousionServer;

let telegram_voiceflousion_server = VoiceflousionServer::<TelegramClient>::new({
        |update, client| Box::pin(base_dialog_handler(update, client))
    })
    .set_clients_manager(telegram_client_manager);

let whatsapp_voiceflousion_server = VoiceflousionServer::<WhatsAppClient>::new({
        |update, client| Box::pin(base_dialog_handler(update, client))
    })
    .set_clients_manager(whatsapp_client_manager);

运行服务器：启动服务器以监听传入的 webhook 请求。

let telegram_voiceflousion_server_closure = async {
    telegram_voiceflousion_server.run(([127, 0, 0, 1], 8080)).await;
};

let whatsapp_voiceflousion_server_closure = async {
    whatsapp_voiceflousion_server.run(([127, 0, 0, 1], 8081)).await;
};

tokio::join!(telegram_voiceflousion_server_closure, whatsapp_voiceflousion_server_closure);

接收 webhook 地址：从控制台复制提供的 URL，并在 Meta 开发者平台上的 Telegram API 和 WhatsApp 应用程序中设置 webhook。

Server is set on 127.0.0.1:8080
Bots without authentication token are available on 127.0.0.1:8080/telegram/:id
Bots with authentication token are available on 127.0.0.1:8080/telegram/:id/?token=<token>
Server is set on 127.0.0.1:8081
Bots without authentication token are available on 127.0.0.1:8081/whatsapp/:id
Bots with authentication token are available on 127.0.0.1:8081/whatsapp/:id/?token=<token>

依赖项

运行项目所需的依赖项在 example/Cargo.toml 文件中列出。对于自定义集成，您可能还需要 async-trait 包。

用法

使用此框架，您可以轻松灵活地将您的机器人与预构建的 Telegram 和 WhatsApp 集成集成，创建强大且可配置的机器人管理系统。Voiceflousion 还提供了通过实现 Client、Update、Sender 和 Responder 特性来创建自定义集成的工具包。一旦实现，您就可以像示例中演示的那样使用您的自定义客户端。要使用与您的自定义 Client 类型相同的 VoiceflousionServer，您还需要实现 ServerClient 特性。

贡献

欢迎贡献！请分叉存储库并提交拉取请求。

许可证

本项目采用 MIT 许可证 - 详细内容请参阅 LICENSE 文件。

作者

Vondert (Ivan Milennyi)

Github: https://github.com/Vondert

LinkedIn: https://www.linkedin.com/in/ivan-milennyi-1084842a5/

X: https://x.com/Vondert1

Email: [email protected]