Introduction

VoiceOI is an enterprise-grade orchestration layer built for organizations that need to run high-volume AI voice operations. By decoupling the core logic (Master Server) from the execution layer (Bot Nodes), we enable sub-100ms latency and unlimited horizontal scalability.

Key Features

Real-time script synchronization
Distributed node orchestration
Direct VICIdial Carrier integration
High-performance Redis event bus

Ready to start?

Skip the fluff and get into production in 15 minutes.

Core Architecture

Our architecture follows a hybrid design: **Centralized Logic, Decentralized Execution.**

1. The Master Server

The Master Server acts as the source of truth for all scripts, campaigns, and organization settings. It exposes a secure API for the admin dashboard and a specialized Sync API for bot nodes. When you update a script, the Master broadcasts this change to the relevant Redis channel.

2. The Bot Nodes

Bot Nodes are lightweight workers that handle the actual AGI (Asterisk Gateway Interface) or Webhook requests. They maintain a local cache of scripts to ensure 0-latency execution even during master server maintenance. They utilize a persistent Redis connection to receive real-time "hot-patch" updates.

Security Model

Traffic between Master and Bots is authenticated via an X-Organization-Secret header. We recommend isolating nodes in a private VPC and using the Master Server as a reverse-proxy Gateway if exposing them publicly.

Master Server Config

Ensure your environment variables are correctly configured for production scale.

Environment Variables (.env)

# Database
DB_HOST=your-postgres-host
DB_PORT=5432
DB_USER=voi_admin
DB_PASS=secure_password
DB_NAME=voiceoi

# Redis (Event Bus)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=if_any

# Security
JWT_SECRET=super_secret_for_dashboard
SYNC_SECRET_SALT=random_string_for_org_keys

**Note:** The `SYNC_SECRET_SALT` is used to derive individual organization keys. Protect this with extreme caution.

Bot Node Deployment

Bot nodes are deployed using a "thin client" approach. You don't need a database on the node; it pulls everything it needs from the Master.

Deployment Steps

Build Artifact: Run `npm run build:bot` on the Master server to generate the optimized production package.

Transfer: Copy the `dist/` and `package.json` to your target node server.

Configure: Set `SERVICE_MODE=bot` and `SYNC_MASTER_URL=https://master.yourdomain.com`.

PM2 Command

pm2 start dist/index.js --name "voiceoi-bot" -- \
  SERVICE_MODE=bot \
  SYNC_MASTER_URL=http://master-ip:4000 \
  SYNC_SECRET_KEY=PASTE_KEY_FROM_DASHBOARD

VICIdial Integration

This is where VoiceOI shines. It replaces traditional script hosting with a dynamic AGI-compatible layer.

Admin - > System Settings

Ensure your VICIdial is allowed to communicate with the Node IP on the specified port (default 4573 for AGI).

Example Dialplan

exten => _X.,1,AGI(agi://localhost:4573/agi, campaign_id=123, org_id=abc)
exten => _X.,n,Hangup()

Pro TipPass variables like `campaign_id` directly in the AGI URI. The Bot Node will automatically pull the correct script and logic from the Master Server based on these parameters.

API Reference

GET/api/sync/campaigns

Master -> Bot

Returns the full configuration bundle for an organization. Used by bots on cold-start.

Header Required

X-Sync-Token

Query Params

org_id

POST/api/sync/logs

Bot -> Master

High-throughput ingestion for call logs and agent activity.

{ "call_id": "...", "duration": 45, "status": "no_answer" }

System V2.1.4