mod_event_agent - FreeSWITCH Event & Command Hub

Production-ready FreeSWITCH module that transforms your PBX into a cloud-native microservice with real-time event streaming and remote command execution via NATS message broker.

📖 Overview

mod_event_agent is a high-performance FreeSWITCH module that enables:

🎯 Remote API Control: Execute any FreeSWITCH command from external services
📡 Real-Time Event Streaming: Publish FreeSWITCH events to message brokers
🎛️ Dynamic Dialplan Control: Park/unpark calls with audio modes (silence, ringback, music)
🔄 Bidirectional Communication: Request-reply and pub/sub patterns
🌐 Multi-Node Support: Cluster-aware with node identification
🚀 Production Performance: 10k+ commands/sec, <1ms latency

Key Use Cases

Call Center Integration: Control FreeSWITCH from CRM/ERP systems
Smart IVR: Dynamic dialplan management from external business logic
Real-Time Analytics: Stream call events to data pipelines
Multi-Tenant Systems: Isolated control per tenant with node routing
WebRTC Gateways: Bridge SIP/WebRTC with external signaling

Standard Response Envelope

Every synchronous command reply comes in the same JSON envelope so client code can be minimal and safe:

{
  "success": true,
  "status": "success",
  "message": "API command executed",
  "timestamp": 1736123456789012,
  "node_id": "fs-node-01",
  "data": "optional payload"
}

timestamp is expressed in microseconds since epoch for maximum resolution.
node_id is always present (or "unknown" if the node was not configured).
Handlers can extend the payload with extra keys like mode, enabled, or info, but the envelope is guaranteed.

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        NATS MESSAGE BROKER                        │
│                      (Pub/Sub + Request/Reply)                    │
│                                                                    │
│  Subjects:                                                         │
│  • freeswitch.api                        ← Broadcast command lane        │
│  • freeswitch.node.{node_id}             ← Direct node lane              │
│  • freeswitch.events.*                  → Events (pub/sub)               │
└────────┬──────────────────────────────────────────┬──────────────┘
         │                                          │
    ┌────▼─────────┐                       ┌────────▼──────────┐
    │   Clients    │                       │  Event Consumers  │
    │              │                       │                   │
    │ • Python     │                       │ • Analytics       │
    │ • Node.js    │                       │ • CDR Processing  │
    │ • Go/Java    │                       │ • Monitoring      │
    │ • Any Lang   │                       │ • ML Pipelines    │
    └──────────────┘                       └───────────────────┘
         ▲                                          ▲
         │                                          │
┌────────┴──────────────────────────────────────────┴──────────────┐
│                      mod_event_agent                              │
│  ┌──────────────┐  ┌───────────────┐  ┌──────────────────────┐  │
│  │   Commands   │  │    Events     │  │      Dialplan        │  │
│  │   Handler    │  │   Adapter     │  │      Manager         │  │
│  │              │  │               │  │                      │  │
│  │ • API calls  │  │ • Streaming   │  │ • Park mode          │  │
│  │ • Originate  │  │ • Filtering   │  │ • Audio control      │  │
│  │ • Bridge     │  │ • JSON format │  │ • Dynamic XML        │  │
│  └──────┬───────┘  └───────┬───────┘  └─────────┬────────────┘  │
│         │                  │                     │               │
│         └──────────────────┴─────────────────────┘               │
│                            │                                     │
│                   ┌────────▼────────┐                            │
│                   │  NATS Driver    │                            │
│                   │  • Pub/Sub      │                            │
│                   │  • Req/Reply    │                            │
│                   │  • Auto-reconnect│                           │
│                   └─────────────────┘                            │
└───────────────────────────┬──────────────────────────────────────┘
                            │
                 ┌──────────▼───────────┐
                 │   FreeSWITCH Core    │
                 │   • Event System     │
                 │   • API Engine       │
                 │   • XML Dialplan     │
                 │   • Call Processing  │
                 └──────────────────────┘

🔁 Command Routing

Publish to freeswitch.api for broadcast commands. Optionally add "node_id":"fs-node-01" in the payload to have a single node pick it up.
Publish to freeswitch.node.{node_id} when you want to address a specific FreeSWITCH node directly (no node_id field required).
Every payload must include a command string. Built-in handlers cover originate, hangup, dialplan.enable, dialplan.disable, dialplan.audio, dialplan.autoanswer, dialplan.status, and agent.status. Any other value falls back to native FreeSWITCH api execution, so {"command":"show","args":"channels"} still works.
Add "async": true to make any command fire-and-forget. The request will be executed but no reply will be published; errors are still logged server-side for observability.

This registry-driven approach keeps clients simple (only two subjects to remember) while letting the server retain full validation, RBAC, and telemetry per command name.

✨ Features

🎯 Remote Control Commands

1. Generic API Execution

Execute any FreeSWITCH API command remotely:

nats req freeswitch.api '{"command":"status"}'
nats req freeswitch.api '{"command":"show","args":"channels"}'
nats req freeswitch.api '{"command":"reloadxml"}'

2. Call Origination

Create outbound calls with full control:

{
  "command": "originate",
  "endpoint": "user/1000",
  "destination": "&park",
  "caller_id_name": "Bot",
  "caller_id_number": "5551234",
  "variables": {"custom_var": "value"}
}

3. Call Bridging

Connect two legs dynamically using native FreeSWITCH commands:

{
  "command": "uuid_bridge",
  "args": "abc-123-uuid sofia/gateway/provider/5551234"
}

4. Statistics & Monitoring

Real-time module metrics:

{
  "command": "agent.status",
  "version": "2.0.0",
  "uptime": 3600,
  "events_published": 12345,
  "commands_received": 5432,
  "driver": "nats",
  "connected": true
}

🛡️ Payload Validation Helpers

Every built-in command now uses the lightweight validators under src/validation/. They provide type-safe binding and descriptive errors without relying on giant schema files or runtime allocations. The helpers follow the v_<type>() pattern and automatically write the sanitized value into your payload struct:

typedef struct {
  char endpoint[256];
  char extension[256];
} call_originate_payload_t;

call_originate_payload_t payload = {0};
const char *err = NULL;

if ((err = v_string(request->payload, &payload, endpoint,
          v_len(1, 255),
          "endpoint must be between 1 and 255 characters"))) {
  return command_result_error(err);
}

if ((err = v_enum(request->payload, &payload, mode,
          "mode must be silence, ringback, or music",
          "silence", "ringback", "music"))) {
  return command_result_error(err);
}

Available helpers:

v_string / v_string_opt with v_len, v_len_min, v_len_max
v_number / v_number_opt with v_range rules
v_bool / v_bool_opt
v_enum / v_enum_opt

They short-circuit on the first failure so command handlers stay tiny while clients receive human readable messages.

🎛️ Dynamic Dialplan Control

Control call flow without reloading dialplan:

Park Mode with Audio Options

# Enable park with ringback tone
nats req freeswitch.api '{"command":"dialplan.enable"}'
nats req freeswitch.api '{"command":"dialplan.audio","mode":"ringback"}'

# Music on hold
nats req freeswitch.api '{"command":"dialplan.audio","mode":"music","music_class":"moh"}'

# Silent park
nats req freeswitch.api '{"command":"dialplan.audio","mode":"silence"}'

# Disable park (return to normal dialplan)
nats req freeswitch.api '{"command":"dialplan.disable"}'

Auto-Answer Configuration

{
  "command": "dialplan.autoanswer",
  "enabled": true  // Auto-answer parked calls
}

Use Cases:

Queue management (park until agent available)
Call recording preparation
IVR delays with custom audio
Emergency broadcast mode

📊 Event Streaming

Stream FreeSWITCH events in real-time:

Configurable Filtering:

<param name="include-events" value="CHANNEL_CREATE,CHANNEL_DESTROY,CHANNEL_ANSWER"/>
<param name="exclude-events" value="HEARTBEAT,PRESENCE_IN"/>

Event Format (JSON):

{
  "event_name": "CHANNEL_ANSWER",
  "timestamp": 1733433600000000,
  "node_id": "fs_node_01",
  "uuid": "abc-123-uuid",
  "headers": {
    "Caller-Destination-Number": "5551234",
    "Channel-State": "CS_EXECUTE"
  }
}

Published to: freeswitch.events.channel.answer, freeswitch.events.channel.create, etc.

🔗 Multi-Node Support

Route commands to specific nodes:

Broadcast (all nodes, filtered):

{"command": "status", "node_id": "fs_node_01"}

Direct (specific node):

Subject: freeswitch.api.fs_node_01
Payload: {"command": "status"}

🚀 Performance Characteristics

Metric	Value
Command Throughput	10,000+ req/sec
Latency (local)	<1ms p99
Event Overhead	<0.1% CPU
Memory	~5MB baseline
Network	<100 KB/s idle

🚦 Quick Start

1. Install NATS Server

# Docker (recommended)
docker run -d --name nats -p 4222:4222 -p 8222:8222 nats:alpine

# Or download binary (no dependencies)
# https://nats.io/download/

2. Compile Module

make clean && make WITH_NATS=1
sudo make install

3. Configure FreeSWITCH

Edit /etc/freeswitch/autoload_configs/event_agent.conf.xml:

<configuration name="event_agent.conf" description="Event Agent Module">
  <settings>
    <param name="driver" value="nats"/>
    <param name="url" value="nats://localhost:4222"/>
    <param name="subject_prefix" value="freeswitch"/>
    <param name="node-id" value="fs-node-01"/>
    
    <!-- Event filtering -->
    <param name="include-events" value="CHANNEL_CREATE,CHANNEL_ANSWER,CHANNEL_HANGUP"/>
    <!-- <param name="exclude-events" value="HEARTBEAT"/> -->
  </settings>
</configuration>

Logging note: mod_event_agent now writes straight through switch_log_printf, so you should manage verbosity using the regular FreeSWITCH logging commands (for example fs_cli -x "log debug").

4. Load Module

fs_cli -x "load mod_event_agent"
# Or add to modules.conf.xml for auto-load

5. Test Commands

# Using NATS CLI (sync request)
nats req freeswitch.api '{"command":"show","args":"modules"}' --server nats://localhost:4222

# Using NATS CLI (async fire-and-forget)
nats pub freeswitch.api '{"command":"originate","endpoint":"user/1000","extension":"&park","async":true}'

# Using web interface
cd example
npm install
node server.js
# Open http://localhost:3000

📁 Project Structure

mod_events_agent/
├── src/
│   ├── mod_event_agent.c          # Module entry point
│   ├── mod_event_agent.h          # Main header
│   │
│   ├── core/                      # Configuration helpers
│   │   └── config.c               # XML config parser
│   │
│   ├── events/                    # Event streaming
│   │   ├── adapter.c              # Event subscription & publishing
│   │   └── serializer.c           # JSON serialization
│   │
│   ├── dialplan/                  # Dynamic dialplan control
│   │   ├── manager.c              # XML binding & park mode
│   │   └── commands.c             # NATS command handlers
│   │
│   ├── commands/                  # Remote command handlers
│   │   ├── handler.c              # Command dispatcher
│   │   ├── core.c                 # Request validation
│   │   ├── api.c                  # Generic API execution
│   │   ├── call.c                 # Originate/Hangup commands
│   │   └── status.c               # Statistics & health
│   │
│   ├── validation/                # Shared payload helpers
│   │   ├── validation.c           # v_string/v_enum/... implementations
│   │   └── validation.h           # Helper macros (v_len, v_range, etc.)
│   │
│   └── drivers/                   # Message broker drivers
│       ├── interface.h            # Driver interface definition
│       └── nats.c                 # NATS implementation
│
├── docs/
│   ├── API.md                     # Complete API reference
│   ├── DIALPLAN_CONTROL.md        # Dialplan control guide
│   └── ROADMAP.md                 # Driver development roadmap
│
├── example/                        # Web interface example
│   ├── server.js                  # Node.js HTTP server (native)
│   ├── package.json               # NATS dependency only
│   └── public/
│       └── index.html             # Complete frontend (Vanilla JS)
│
├── autoload_configs/
│   └── mod_event_agent.conf.xml   # Configuration template
│
└── Makefile                        # Build system

🎯 Available Commands

Command	Description	Reply
`originate`	Create outbound call with endpoint/extension/context fields	✅ Yes
`hangup`	Terminate a UUID with optional `cause`	✅ Yes
`agent.status`	Module stats (version + metrics)	✅ Yes
`dialplan.enable`	Enable park mode	✅ Yes
`dialplan.disable`	Disable park mode	✅ Yes
`dialplan.audio`	Configure park audio (`mode`, optional `music_class`)	✅ Yes
`dialplan.autoanswer`	Toggle auto-answer for parked calls	✅ Yes
`dialplan.status`	Snapshot of park manager state	✅ Yes

Any other command value is passed directly to the native FreeSWITCH API, so "command":"status", "command":"show", "command":"uuid_bridge", etc., keep working without extra configuration.

ℹ️ Bridge, transfer, and media manipulation go through the native API fallback with commands such as uuid_bridge, uuid_transfer, uuid_broadcast, etc.

Async Delivery

Add "async": true to any payload when you do not need a reply. The server still executes the handler, updates metrics, and logs errors, but the request immediately returns on the client side.

Events (Pub/Sub)

Subject Pattern	Description
`freeswitch.events.channel.*`	Channel lifecycle events
`freeswitch.events.call.*`	Call-related events
`freeswitch.events.custom.*`	Custom events

Full API documentation: docs/API.md

🔧 Configuration Options

Basic Settings

<param name="driver" value="nats"/>              <!-- Driver: nats (others in roadmap) -->
<param name="url" value="nats://host:4222"/>     <!-- Broker connection URL -->
<param name="subject_prefix" value="freeswitch"/> <!-- Subject prefix (freeswitch.api, freeswitch.node.*) -->
<param name="node-id" value="fs-node-01"/>       <!-- Unique node identifier -->

NATS-Specific

🚀 Installation

Requirements

FreeSWITCH 1.10+ (headers installed in /usr/local/freeswitch/include or equivalent)
Linux/Unix system
build toolchain: gcc, make, pkg-config
libcjson headers (libcjson-dev on Debian/Ubuntu)
libssl/libcrypto headers (libssl-dev)
NATS Server (runtime dependency)
Bundled NATS C client (already in lib/ + include/ — no extra install needed)

Installation Flow

Build the module (use the same commands listed in Quick Start step 2).
Copy mod_event_agent.so into /usr/local/freeswitch/mod/.
Copy autoload_configs/mod_event_agent.conf.xml into /usr/local/freeswitch/conf/autoload_configs/.
Add <load module="mod_event_agent"/> to modules.conf.xml if it is not already present.
Restart FreeSWITCH (systemctl restart freeswitch or an equivalent command for your distribution).

Container tip: Run ./install.sh inside the FreeSWITCH container to automate steps 2 and 3. The script auto-detects container paths and applies the same layout used on bare metal.

Dev stacks: The docker-compose.dev.yaml file provisions FreeSWITCH + NATS for local testing if you prefer a fully containerized workflow.

⚙️ Configuration

Edit /usr/local/freeswitch/conf/autoload_configs/mod_event_agent.conf.xml:

<configuration name="mod_event_agent.conf" description="Event Agent Module">
  <settings>
    <!-- Driver selection: nats (current implementation) -->
    <param name="driver" value="nats"/>
    
    <!-- Message broker URL -->
    <param name="url" value="nats://localhost:4222"/>
    
    <!-- Node identification (for multi-node clusters) -->
    <param name="node-id" value="fs-node-01"/>
    
    <!-- NATS specific settings -->
    <param name="nats-timeout" value="5000"/>           <!-- Connection timeout (ms) -->
    <param name="nats-max-reconnect" value="60"/>       <!-- Max reconnection attempts -->
    <param name="nats-reconnect-wait" value="2000"/>    <!-- Wait between reconnects (ms) -->
  </settings>
</configuration>

Multi-Node Configuration

For FreeSWITCH clusters, assign a unique node-id to each node:

<!-- Node 1 -->
<param name="node-id" value="fs-node-01"/>

<!-- Node 2 -->
<param name="node-id" value="fs-node-02"/>

Clients can filter responses by node_id in the JSON response.

🎯 Quick Usage

Install NATS Server

# Docker (~10MB image)
docker run -d --name nats -p 4222:4222 nats:latest

# Or direct binary (https://nats.io/download/)
wget https://github.com/nats-io/nats-server/releases/download/v2.10.7/nats-server-v2.10.7-linux-amd64.tar.gz
tar xzf nats-server-*.tar.gz
./nats-server

Compile Example Clients

Build the helper binaries under tests/ with the provided Makefile, then run:

cd tests

# service_a client: Sends commands and receives responses
LD_LIBRARY_PATH=../lib/nats ./bin/service_a_nats '{"command":"status"}'

# service_b client: Processes commands (simulation)
LD_LIBRARY_PATH=../lib/nats ./bin/service_b_nats

# simple client: Multi-mode (pub/req/server)
LD_LIBRARY_PATH=../lib/nats ./bin/simple_test req freeswitch.api '{"command":"version"}'

Command Examples

# System status
./bin/show_modules_test 
# → {"success":true,"message":"API command executed","data":"(list modules)","timestamp":...,"node_id":"fs-node-01"}

See docs/API.md for complete command documentation.

📊 Comparison vs ESL

Aspect	mod_event_agent + NATS	ESL (Event Socket Library)
Protocol	NATS (text, open standard)	Proprietary binary
Dependencies	None (static lib)	libesl + ~7MB deps
Debugging	`telnet`, `nats` CLI, any tool	Specific ESL client
Languages	Any with NATS client	Specific bindings (Node, Python, etc.)
Latency	0.5-1ms (local)	2-5ms
Throughput	~10,000 req/s	~1,000 req/s
Scalability	Native (NATS clustering)	Requires proxy/balancer
Event Streaming	Native Pub/Sub	Socket connection 1:1
Multi-Node	Yes (node filtering)	Multiple connections

🧪 Testing

⚠️ DEVELOPMENT MODE: This module is under active development. Currently there is only one functional test as a reference.

Available Test

`show_modules_test`

NATS client that verifies module loading by sending the show modules command:

Expected output:

{
  "success": true,
  "message": "API command executed",
  "data": "type,name,ikey,filename\n...\ngeneric,mod_event_agent,mod_event_agent,/usr/local/freeswitch/mod/mod_event_agent.so\n...",
  "timestamp": 1764915137308268,
  "node_id": "fs-node-01"
}

Future Tests (Roadmap)

More tests will be added to cover:

✅ Generic API commands (status, version, global_getvar)
🚧 Async commands (originate, hangup)
🚧 Event streaming (FreeSWITCH event subscription)
🚧 Performance benchmarks (throughput, latency)
🚧 Multi-node scenarios (node filtering)
🚧 Concurrent clients (race conditions)

Validated Performance (Production)

✅ 100,000 requests: 100% success rate
✅ 50 concurrent clients: No packet loss
✅ Production: 1,055 requests, 99.7% success
✅ Latency: <100ms (average <1ms local)

1. Distributed Microservices

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Service A  │────▶│    NATS     │◀────│  Service B  │
│  (Node.js)  │     │   Broker    │     │   (Python)  │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                    ┌──────▼──────┐
                    │ FreeSWITCH  │
                    │ mod_event   │
                    │   _agent    │
                    └─────────────┘

- Multiple services control FreeSWITCH without direct dependencies
- Horizontal broker scalability
- Heterogeneous languages (Node, Python, Go, Java, etc.)

2. Event-Driven Architecture

FreeSWITCH Events → NATS → [
    • Analytics Service (Python)
    • Billing Service (Go)
    • Notification Service (Node.js)
    • CDR Storage (Java)
]

- Real-time event streaming
- Parallel event processing
- Total decoupling between producers and consumers

3. Distributed Call Center

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ FreeSWITCH 1 │  │ FreeSWITCH 2 │  │ FreeSWITCH 3 │
│ (New York)   │  │ (London)     │  │ (Tokyo)      │
└───────┬──────┘  └───────┬──────┘  └───────┬──────┘
        │                 │                  │
        └─────────────────┴──────────────────┘
                          │
                    ┌─────▼─────┐
                    │   NATS    │
                    │  Cluster  │
                    └─────┬─────┘
                          │
                ┌─────────┴─────────┐
        ┌───────▼────────┐  ┌──────▼───────┐
        │  Control Panel │  │   Monitor    │
        │   (Web UI)     │  │  Dashboard   │
        └────────────────┘  └──────────────┘

- Centralized control of multiple FreeSWITCH nodes
- Geographic load balancing
- Real-time global monitoring

🛠️ Driver Development

See docs/ROADMAP.md for details on implementing new drivers.

Implementing a New Driver

Copy template: cp src/drivers/driver_nats.c src/drivers/driver_mydriver.c
Implement interface: Complete all event_driver_t methods
Add to Makefile: Add WITH_MYDRIVER=yes flag
Testing: Create tests in tests/
Documentation: Update docs/ROADMAP.md

Driver Interface

typedef struct event_driver {
    // Initialization
    switch_status_t (*init)(const char *url, const char *node_id);
    
    // Cleanup
    void (*shutdown)(void);
    
    // Commands (request-reply)
    switch_status_t (*subscribe_commands)(command_callback_t callback);
    switch_status_t (*send_command_response)(const char *reply_subject, 
                                             const char *json_response);
    
    // Events (pub/sub)
    switch_status_t (*publish_event)(const char *subject, 
                                     const char *json_payload);
    
    // Health check
    switch_bool_t (*is_connected)(void);
} event_driver_t;

📚 Documentation

docs/API.md: Complete API reference
- JSON payload formats
- Available commands (sync/async)
- Response codes
- Usage examples
docs/ROADMAP.md: Drivers roadmap
- Current status of each driver
- Implementation guides
- Contributions
example/README.md: Web interface example
- Vanilla JS implementation
- Node.js native server
- Real-time call control

🙏 Credits

FreeSWITCH: https://freeswitch.org/
NATS: https://nats.io/
NATS C Client: https://github.com/nats-io/nats.c

📞 Support

Issues: https://github.com/zenozaga/mod_events_agent/issues
Documentation: docs/
Web Interface: example/

📄 License

MIT License - See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
autoload_configs		autoload_configs
docs		docs
example		example
include/nats		include/nats
lib/nats		lib/nats
src		src
tests/src		tests/src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.freeswitch		Dockerfile.freeswitch
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.dev.yaml		docker-compose.dev.yaml
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

mod_event_agent - FreeSWITCH Event & Command Hub

📖 Overview

Key Use Cases

Standard Response Envelope

🏗️ Architecture

🔁 Command Routing

✨ Features

🎯 Remote Control Commands

1. Generic API Execution

2. Call Origination

3. Call Bridging

4. Statistics & Monitoring

🛡️ Payload Validation Helpers

🎛️ Dynamic Dialplan Control

Park Mode with Audio Options

Auto-Answer Configuration

📊 Event Streaming

🔗 Multi-Node Support

🚀 Performance Characteristics

🚦 Quick Start

1. Install NATS Server

2. Compile Module

3. Configure FreeSWITCH

4. Load Module

5. Test Commands

📁 Project Structure

🎯 Available Commands

Async Delivery

Events (Pub/Sub)

🔧 Configuration Options

Basic Settings

NATS-Specific

🚀 Installation

Requirements

Installation Flow

⚙️ Configuration

Multi-Node Configuration

🎯 Quick Usage

Install NATS Server

Compile Example Clients

Command Examples

📊 Comparison vs ESL

🧪 Testing

Available Test

show_modules_test

Future Tests (Roadmap)

Validated Performance (Production)

1. Distributed Microservices

2. Event-Driven Architecture

3. Distributed Call Center

🛠️ Driver Development

Implementing a New Driver

Driver Interface

📚 Documentation

🙏 Credits

📞 Support

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`show_modules_test`

Packages