Skip to content

Telephony — Architecture overview

Introduction

The xynap telephony system is based onFreeSwitch v1.10.10as a central SIP engine and offers two parallel signal paths: a classic PBX for internal and external telephony as well as a AI-assisted voice pipeline via LiveKit.

All configuration data (Extensions, Trunks, DIDs, Ring Groups) are provided dynamically via thePlatform API, FreeSwitch does not hold static XML files for phone numbers or routing.

Dual-Path architecture

SIP Provider (1&1 / Plusnet)
    │ SIP (UDP 5060)
    ▼
┌──────────────────────────────────────────────────┐
│  FreeSwitch (Container: voicebot-fs)             │
│  network_mode: host                              │
│                                                  │
│  ┌─────────────────────┐ ┌─────────────────────┐ │
│  │  Path A: PBX        │ │  Path B: LiveKit    │ │
│  │  mod_xml_curl       │ │  livekit-sip :5070  │ │
│  │  → Platform API     │ │                     │ │
│  │    :8001             │ │  ┌───────────────┐  │ │
│  │                     │ │  │ AI Voice Bot  │  │ │
│  │  ┌───────────────┐  │ │  │ Dolmetscher   │  │ │
│  │  │ Extensions    │  │ │  │ LiveKit Rooms  │  │ │
│  │  │ Ring Groups   │  │ │  │ Agent Workers │  │ │
│  │  │ IVR Menues    │  │ │  └───────────────┘  │ │
│  │  │ WebRTC (WSS)  │  │ │                     │ │
│  │  │ Outbound      │  │ │                     │ │
│  │  └───────────────┘  │ └─────────────────────┘ │
│  └─────────────────────┘                         │
└──────────────────────────────────────────────────┘

Path A — Internal PBX

The classic telephony path usesmod_xml_curlto query thePlatform API auf Port 8001via HTTP POST for every SIP event (registration, incoming call, directory lookup). The API returns dynamically generated XML.

Leistungsumfang:

  • Internal extensions (1000–1099)
  • Ring Groups for departments
  • IVR menus with DTMF and language navigation
  • WebRTC Softphone via WSS (Port 7443, JsSIP)
  • Outbound Calls About Provider Trunks
  • Call Filters (Blacklist / Whitelist)

Path B — LiveKit Agent

For AI-based applications, calls are forwarded to theLiveKit SIP Bridge(Port 5070). The LiveKit server manages spaces where Python-based Agent Workers run.

Anwendungen:

  • AI Voice Bot— Interactive IVR with voice recognition
  • Dolmetscher— Bidirectional real-time translation (Whisper → LibreTranslate → Piper TTS)
  • LiveKit Rooms— Conference and media rooms

Container architecture

Containers Image Network Ports Task
voicebot-fs Custom (drachtio-freeswitch-mrf + mod xml curl) host 5060, 5061, 7443, RTP SIP engine
livekit livekit/livekit-server v1.7 host 7880 Media server
livekit-sip livekit/sip host 5070 SIP Bridge for LiveKit
livekit-agent Custom (Python, livekit-agents 1.4) host — AI-Agent Worker
interpreter-bridge Custom host 9001 Interpreter service

File system reference

Path Description
/usr/local/xynap/voicebot/freeswitch/Dockerfile FreeSwitch Container Image
/usr/local/xynap/voicebot/docker-compose.yml Compose file for Voicebot stack
/etc/xynap/voicebot/freeswitch/ FreeSwitch configuration (volume mount)
/etc/xynap/livekit/livekit.yaml LiveKit server content
/etc/xynap/livekit-sip/sip.yaml LiveKit SIP-Bridge-Config
/usr/local/xynap/platform/backend/app/modules/sip/ Platform API SIP Module
/usr/local/xynap/interpreter/ Interpreter service Source code
/var/lib/xynap/voicebot/tts-audio/ TTS Audio cache

Sofia Profiles

FreeSwitch uses two Sofia profiles for different provider connections:

external-ipv4

  • Bind: Port 5060 on46.4.96.105(only IPv4)
  • Zweck: Plusnet gateway (IP-Auth, no REGISTER)
  • RTP-IP: IPv4

internal

  • Bind: Port 5060 on::(Dual-Stack, IPv4 + IPv6)
  • Zweck: 1&1-Gateways (REGISTER), Internal Extensions, WebRTC
  • ext-sip-ip / ext-rtp-ip:2a01:4f8:140:829d::2(IPv6)
  • TLS: Port 5061
  • WSS: Port 7443 (WebRTC)
  • ACL:sip-gateways(default deny)

IPv6 is mandatory for 1&1

1&1 blocks Hetzner IPv4 addresses. All 1&1-gateways must be registered with IPv6 via theinternalprofile. See Provider Configurationfor details.

Platform API — SIP module

The dynamic configuration runs over a single endpoint:

POST /api/v1/sip/xml-curl

This endpoint is called ** only by localhost (FreeSwitch itself) and requires kein JWT**. Depending on thesectionparameter, it delivers:

Section Function
directory User authentication + gateway discovery
dialplan DID routing in thepublicContext

In addition, the API offers complete CRUD endpoints:

/api/v1/sip/trunks          — Provider-Gateways
/api/v1/sip/extensions       — SIP-Extensions
/api/v1/sip/dids             — Rufnummern (DIDs)
/api/v1/sip/lines            — Line-Zuordnungen
/api/v1/sip/ring-groups      — Gruppenrufe
/api/v1/sip/ivr-menus        — IVR-Menüs
/api/v1/sip/call-filters     — Black-/Whitelists

Live-Statusof the system (registrations, gateway status):

GET /api/v1/sip/live-status

ESL-Integration: The Platform API maintains an asynchronous TCP connection to the FreeSwitch Event Socket. For changes (e.g. new Trunk, modified extension), a reload is automatically triggered.

Network ports

Port Protocol Directions Description
5060 UDP Inbound/Outbound SIP Signaling (Provider + Intern)
5061 TCP/TLS Inbound SIP over TLS
5070 UDP Internal LiveKit SIP-Bridge
7443 TCP/WSS Inbound WebRTC Softphone
7880 TCP Internal LiveKit Server API
8001 TCP Internal Platform API (xml-curl)
9001 TCP Internal Interpreter WebSocket
10000–10060 UDP Inbound/Outbound RTP Media
16384–16484 UDP Inbound/Outbound RTP Media (expanded area)

Host network

All phone containers run withnetwork_mode: host. This is mandatory for correct RTP handling and SIP-NAT-Traversal on Bare-Metal.

Further documentation