6 releases
0.3.1 | Aug 21, 2024 |
---|---|
0.3.0 | Aug 19, 2024 |
0.2.0 | Aug 4, 2024 |
0.1.2 | Jul 26, 2024 |
#379 in Web programming
387 downloads per month
355KB
4K
SLoC
Voiceflousion
Voiceflousion is a framework designed to integrate chatbots from the Voiceflow chatbot constructor into any chat platform. Currently, it supports Voiceflow bots integration with Telegram and WhatsApp, with future plans for Instagram, Discord, and more. The framework also provides its own web server for launching chatbots and tools for creating custom integrations for any chat platform, supporting message formats such as text, buttons, images, cards, and carousels.
Features
- Telegram and WhatsApp Integration: Supports text, buttons, images, cards, and carousels.
- Custom Integrations: Tools provided for developing integrations for any chat platform with minimal code.
- Session Management: Fully automated user and bot session management (creation, cleanup, validation, synchronization guarantees).
- Scalability: Supports multiple client bots for a single Voiceflow bot, and multiple Voiceflow bots and clients on a single server.
- Admin Capabilities: Features for creating an admin interface, such as retrieving all bot sessions, activating, and deactivating user sessions.
- Extensibility: Easily extendable to support additional platforms like Instagram and WhatsApp.
- Multi-User Support: The client bot supports multiple users simultaneously and offers flexible settings for the maximum number of users, session validity time, and cleanup interval.
- Voiceflousion server: Web server for launching and managing chatbots without needing of external dependencies.
- Custom handlers: Developer can write a custom function for processing bot's workflow, for example save conversation parts into database.
- Server security opportunities: Bot authentication tokens and allowed origins setting for Voiceflousion server.
Installation and Setup
Prerequisites
- Rust (latest stable version)
- Cargo (Rust package manager)
- A ready Voiceflow bot, including its API key, bot ID, and version ID
- Telegram or WhatsApp bots created with their respective tools, including their API keys
Environment Variables
It is recommended to store sensitive information like API keys in a .env
file. Here is an example of the .env
file content:
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
Quick Start: Running the Example Project
Clone the repository:
git clone https://github.com/Vondert/voiceflousion.git
cd voiceflousion
Navigate to the example directory:
cd example
Rename .env.example
to .env
and fill in the required information:
mv .env.example .env
Install dependencies and run the example:
cargo run --release
Adding Voiceflousion into Your Project (Telegram and WhatsApp)
Set Up the Environment
Create a .env
file in the root directory of your project with the necessary variables:
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
Add Dependencies
Add the following dependencies to your Cargo.toml
file:
[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"] }
Set Up the Main File
Load Environment Variables: Use dotenv to load environment variables from the .env
file.
use dotenv::dotenv;
dotenv().ok();
Retrieve Environment Variables: Get the necessary API keys and IDs from the environment.
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());
Initialize Voiceflow Client: Create a new VoiceflowClient
instance.
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));
Build Telegram Client and WhatsApp Client: Set up the TelegramClient
and WhatsAppClient
with session management.
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);
Build Telegram Client and WhatsApp Client managers: Set up the ClientManager
with created clients
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]));
Set Up Voiceflousion server: Create VoiceflousionServer
with previously built ClientManager
instances and set up the base dialog handler for handling updates from clients.
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);
Run the Server: Start the server to listen for incoming webhook requests.
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);
Receive webhook address: Copy given urls from console and set webhook with Telegram API and in WhatsApp application on Meta developers platform.
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>
Dependencies
The dependencies required to run the project are listed in the example/Cargo.toml file. For custom integrations, you may need the async-trait
crate.
Usage
By using this framework, you can easily and flexibly integrate your bots with pre-built integrations for Telegram and WhatsApp, create powerful and configurable bot management system. Voiceflousion also provides toolkit for creating custom integrations by implementing the Client
, Update
, Sender
, and Responder
traits. Once implemented, you can use your custom client in the same way as demonstrated in the example. For using VoiceflousionServer
with your custom Client
type you also need to implement ServerClient
trait.
Contributing
Contributions are welcome! Please fork the repository and submit a pull request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Author
Vondert (Ivan Milennyi)
Github: https://github.com/Vondert
Linkedin: https://www.linkedin.com/in/ivan-milennyi-1084842a5/
Email: 25042018avic@gmail.com
Dependencies
~7–20MB
~320K SLoC