rajunify123/freeswitch-voicebot repository overview

⁠🤖 FreeSWITCH Automated AI VoiceBot

An automated, real-time IVR VoiceBot that handles inbound telephone calls via FreeSWITCH, transcribes caller speech, and navigates a dynamic JSON-defined conversation flow. Powered by Silero VAD, DeepFilterNet2 neural noise cancellation, and Whisper STT—all in a single, ready-to-run container!

⁠🌟 Why This VoiceBot?

This image is a complete, production-ready solution that turns any standard SIP/VoIP telephone line into an interactive AI voice conversation. It is designed to handle high-fidelity audio streams, clean background noise in real-time, and route callers through conversational trees with high semantic accuracy.

⁠🚀 Key Technical Highlights

• 📦 All-in-One Container: Includes FreeSWITCH, Redis, FastAPI WebSocket Server, and an ESL (Event Socket Library) orchestrator agent, all pre-configured and managed cleanly by supervisord.
• ⚡ Sub-Second Latency: Uses Silero VAD for ultra-fast, local speech detection. No roundtrips to the cloud just to figure out if someone is talking!
• 🧠 Deep Noise Cancellation: Integrates DeepFilterNet2 neural networks to filter out street noise, wind, and background static before sending audio for transcription.
• 🗣️ Whisper STT Integration: Streams chunked audio and issues ultra-fast transcription queries directly to a high-speed Whisper backend.
• 🎯 Smart Router (Fuzzy + Semantic): Custom JSON IVR Engine that matches user intent using hybrid matching:
  • Pass 1: Fast fuzzy matching for keyword shortcuts and standard synonym expansions (e.g., yes/no).
  • Pass 2: Semantic cosine-similarity matching (via sentence-transformers) to capture intent even when callers use different wording.
• 📞 Enterprise Ready: Supports concurrent channels (up to 5 in default settings) with dedicated per-call audio pipelines, sound buffers, and full state locking using Redis.

⁠🏗️ How It Works

+-----------------------------------------------------------+
|                   FreeSWITCH Container                     |
|                                                            |
|   +--------------+          +------------------------+     |
|   |  mod_sofia   |--------->|    mod_audio_fork      |     |
|   |  (SIP Stack) |          |  (WebSocket Streamer)  |     |
|   +--------------+          +-----------+------------+     |
+----------------------------------------|------------------+
                                         |
                                         v  WebSocket: 16kHz Mono PCM
+-----------------------------------------------------------+
|                   Python VoiceBot Engine                    |
|                                                            |
|   +---------------------------------------------------+    |
|   |            Per-Call Audio Pipeline                 |    |
|   |                                                   |    |
|   |   1. Silero VAD        - Speech detection         |    |
|   |   2. DeepFilterNet2    - Neural noise cancellation|    |
|   |   3. Whisper STT       - Speech-to-Text          |    |
|   |   4. JSON IVR Engine   - Intent matching         |    |
|   +-------------------------+-------------------------+    |
|                             |                              |
|                             v                              |
|                  [Broadcast Response Audio]                 |
+-----------------------------------------------------------+

⁠🏃 Quick Start Guide

You can launch the complete stack using Docker Compose or as a Standalone Container.

⁠Option A: Using Docker Compose (Recommended)

1. Clone the project files:

   git clone https://github.com/rajshahunify/freeswitch_voicebot.git
   cd freeswitch_voicebot
   

   Copy

2. Spin up the entire environment:

   docker compose up -d
   

   Copy

⁠Option B: Running Standalone Container

Run the image directly with custom environment variables:

docker run -d \
  --name freeswitch-voicebot \
  -p 5060:5060/udp \
  -p 5080:5080/udp \
  -p 8021:8021 \
  -p 16384-16484:16384-16484/udp \
  -e VOICEBOT_EXTENSION=5000 \
  -e EXTERNAL_IP=127.0.0.1 \
  rajunify123/freeswitch-voicebot:latest

⁠📞 Making Your First Test Call

1. Download and open any SIP softphone (e.g., Zoiper, MicroSIP, or Linphone).
2. Configure a new account and point it to your Docker host IP (e.g., 127.0.0.1:5060).
3. Log in with Username: 1000 and Password: 1234.
4. Dial 5000 (or your custom VOICEBOT_EXTENSION).
5. Start talking! The voice bot will answer immediately and engage in a real-time conversation.

⁠🖥️ Choose Your Deployment Mode

This project ships with three Docker Compose files optimized for different platforms and use cases:

⁠🪟 Windows / 🍎 macOS Users

Use the default docker-compose.yml (bridge mode). Docker Desktop on Windows and macOS does not support host networking.

docker compose up -d

⁠🐧 Linux Users

You have two options:

Standard (bridge mode) — same as Windows/macOS:

docker compose up -d

High-performance (host networking) — recommended for production servers with many concurrent calls:

docker compose -f docker-compose.host.yml up -d

⁠🔧 Development Mode (Any Platform)

For active development with live code reloading (source code is volume-mounted into the container):

docker compose -f docker-compose.dev.yml up -d

After editing Python code, restart the services without rebuilding:

docker exec freeswitch-voicebot supervisorctl restart voicebot-server voicebot-agent

After editing FreeSWITCH XML configs:

docker exec freeswitch-voicebot fs_cli -x "reloadxml"

⁠⚙️ Configuration Reference

Customize the behavior of the voicebot using these environment variables:

⁠🛠️ Deploying Custom Conversational Flows

To change how the voice bot answers, simply define your custom dialog steps in your JSON conversation file. You can mount your own custom configurations and audio soundboards into the container:

• Flow Configuration: Mount your custom JSON flow file to /app/ivr/flow.json.
• Audio Assets: Place your .wav prompts in the mounted FreeSWITCH sounds directory at /usr/local/freeswitch/sounds/custom/.

⁠🔗 Code & Support

• 📂 GitHub Repository: github.com/rajshahunify/freeswitch_voicebot⁠
• 🐛 Issue Tracker: Submit bugs or feature requests here⁠
• 📄 License: MIT License. Feel free to use, modify, and build upon this project.