voiceflousion 0.3.1

A crate that provides toolkit for Voiceflow AI bots integrations and pre-built functionality for quick integration with popular messengers
Documentation

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/

X: https://x.com/Vondert1

Email: 25042018avic@gmail.com