AiPBX
AiPBX Documentation
Administrator documentation for AiPBX on 64-bit Linux (Ubuntu 26.04 LTS+, Debian 13+, Raspberry Pi OS 64-bit, and Armbian on x86_64 & ARM64). Start with the installation guide, then use the pages below while configuring the system.
💡 Quick Diagnosis: When something does not work, start with the 🗺️ system map (where everything is) and 🛠️ troubleshooting (symptom → fix).
🚀 Getting started
| Page | What it covers |
|---|---|
| 🚀 Installation & updating | Requirements, one-line installer, certificates, ports, aipbx-update |
| 📺 Video: Installation | Step-by-step setup on YouTube: English · Türkçe · Deutsch |
| 📺 Video: Menu tour | Every screen of the portal on YouTube: English · Türkçe · Deutsch |
| 🖥️ Portal basics | The Apply workflow, edit dialogs, ordering lists, copying records |
| 💾 Backups, recovery & rollback | Reproducible daily backups (aipbx-backup), disaster recovery restore commands, and zero-downtime automated upgrade rollback (aipbx-update) |
| 🏗️ Architecture | Components, traffic flow, security model |
📞 Telephony
| Page | What it covers |
|---|---|
| 🌐 Trunks | Connection modes, inbound DID trimming, transit routing, outbound caller ID normalization, copy / rename / order |
| 🚫 Blacklist & Spam blocker | Inbound spam blocking, AstDB sub-microsecond lookup, wildcards/patterns, drop/busy/congestion/announcement actions |
| 📤 Outbound routes | Dial patterns, number manipulation, trunk failover, route groups, RFC 6442 / RFC 6443 Geolocation emergency headers |
| 🎛️ Call normalization | Pre-filter rules per client origin (Mobile, Desk, Web), E.164 normalization, trunk prefix stripping |
| 📥 Inbound routes (DIDs) | DID matching, destinations, fax DIDs |
| 💻 Custom Dialplan | Custom Asterisk context injection, syntax validator, internal aggregator, recipe templates (Intercom, Spy, Paging, DISA) |
| ☎️ Desk phones | Provisioning Yealink, Grandstream, Fanvil, Snom, Cisco SPA and Poly phones over HTTPS, CSV import, waiting phones, phones found on the network, key layouts (BLF, speed dial, park), re-provision |
| 🔵 Cisco 7900 / 8800 series | Cisco’s enterprise phones (CallManager firmware): the SEP<MAC>.cnf.xml AiPBX writes, the firmware, the usecallmanager.nz Asterisk patch and the shared files you provide |
| 🖧 Network settings | The server’s addresses, the addresses desk phones get, and moving everything after an IP change in one step |
| 🛡️ Reverse proxy setup | Deploying behind Nginx, Caddy, Traefik, HAProxy, Apache; WebRTC WebSocket proxying, trusted proxies, and SIP/RTP bypass |
| 📡 Network services | DHCP (option 66/150/160) TFTP and read-only FTP for desk phones on a phone network or VLAN, leases, the options for your own DHCP server, an NTP server and phone logs (syslog) by IP or MAC |
| 🩺 Health checks | The server watches itself (services, trunks, disk, certificate, backup …), alarm e-mails, the daily summary with yesterday’s calls, aipbx-selftest |
| 🎙️ Call recordings | Where recordings live, automatic MP3 conversion, playback |
| 📊 Reports | Call reports with trunks and direction, Queue Report Centre, PDF and Excel export |
| 🔊 Sounds & languages | Custom sounds, the Turkish prompt packages (six formats), regenerating a prompt |
| 🌍 Translating | Interface languages, adding or correcting a translation with scripts/i18n.py, mobile app texts, prompts in other languages |
| 📹 Video calls | Video between the web phone, the Android app and desk video phones; the one video codec; bandwidth |
| 🎧 WebRTC, NAT and TURN | Browser and app audio across NAT, external IP, TURNS on 443, troubleshooting silent calls |
| 🗄️ External databases & IVR data steps | Read-only MySQL/PostgreSQL connections, encrypted credentials, real-time IVR caller/DTMF data lookups and call branching |
| 🎚️ PBX fine tuning & maintenance | Jitter buffer, SIP protocol timers (T1, B, Max-Forwards), 10-minute SIP debug, safe night restart window, spoken status messages |
| 🐧 Linux OS & kernel tuning | Network sysctl (RTP buffers, MPTCP disable), SIP ALG blacklist, real-time CPU scheduling, OOM protection, needrestart shielding |
🔐 Users and security
| Page | What it covers |
|---|---|
| 👥 Users & roles | Built-in roles, landing pages, permissions, My Phone |
| 🛡️ Security | Firewall, fail2ban, the aipbx-priv root helper, Apache sandbox |
| 🖧 Network ports & firewall | Complete matrix of all TCP/UDP ports, public vs LAN scopes, NAT guidelines, UFW/firewalld/iptables recipes |
| 🛡️ Threat model & attack surface | Security architecture, SIP exposure boundaries, WebRTC/TURNS credentials, recording retention, mobile push tokens, and AI least privilege guardrails |
| ⚖️ GDPR, KVKK & data privacy | Optional regulatory presets (KVKK, GDPR, CCPA/FCC, HIPAA, PCI-DSS, LGPD), pre-call opt-in/opt-out, periodic beep, retention purge, SAR export, Right to Erasure, and Cloud AI lock |
| 📜 Certificates | One certificate for portal, TURNS and SIP-TLS; Let’s Encrypt, upload, renewals |
| 💡 Busy lamps (BLF) | Desk phone keys for colleagues, do-not-disturb, forwarding and queue login; pickup; voicemail lamp |
| ✉️ E-mail | Mail relay and e-mail templates (fax, voicemail, invitations, password e-mails) |
| 🗄️ File storage | Chat attachments on the local disk or in an S3-compatible bucket (AWS S3, MinIO, Wasabi, Backblaze B2), moving existing files |
| 🔑 REST API v1 & outbound webhooks | Stateless /api/v1/* endpoints, OpenAPI 3.1 spec, Bearer API keys (apbx_...), scopes, IP allowlists, and HMAC-SHA256 signed webhooks |
| ⏱️ Scheduled tasks | Sandboxed background shell, PHP and Python scripts on a cron schedule (aipbx-task, systemd-run), run history, bell alarms |
| 🛠️ Troubleshooting | Changes not applied, calls hung up, sounds not found, SIP captures |
🔌 Plugins
Optional applications and integrations bundled with AiPBX (plugins/: official plugins and community plugins), enabled on demand under Integrations → Plugins (/plugins):
| Page | Plugin slug | What it covers |
|---|---|---|
| 🧩 Plugin system & developer guide | — | The bundled plugin catalog (plugins/), plg_* database tables, enabling/disabling integrations (google-auth, ms-teams, …), and building custom .zip plugins |
| 🔑 Corporate SSO: OpenID Connect & SAML 2.0 (Plugins) | oidc-auth, saml-auth |
Enterprise Single Sign-On (SSO) with Microsoft Entra ID (Azure AD), Okta, Keycloak, Authentik, Google Workspace, and ADFS with JIT auto-provisioning |
| 🤖 Auto dialer & AMD campaigns (Plugin) | auto-dialer |
Automated outbound calling campaigns with Answering Machine Detection (AMD), queue free-agent pacing, voicemail drop, and CSV call results |
| 🌐 Website call widget (Plugin) | web-widgets |
“Call us” button for websites (WebRTC in the browser), call-back form, allowed websites and limits, WordPress plugin |
| ☁️ Cloud AI services (Plugin) | ai-cloud, ai-voicemail |
Accounts of cloud AI providers (Gemini/Gemma, OpenAI, Azure, Deepgram, Groq, NVIDIA NIM, Qwen, any OpenAI-compatible service), cloud speech to text, language models, voicemail transcription |
| 🗣️ Cloud TTS (Plugin) | ai-tts |
Text to speech with Google, Amazon Polly, Azure, ElevenLabs or OpenAI; saving announcements |
| 🧠 Local AI models (Plugin) | ai-models |
AI models on the PBX itself (EMA Lightning Turkish TTS): the runtime, downloading models, the aipbx-ai service and its API |
| 🎛️ AI applications (Plugin) | ai-apps |
AI features with their own numbers that take calls: announcements with values (caller, lookup address) |
| ✨ Dialplan editor / AI assistant (Community plugin, @shido6) | ai-assistant |
Plain-language PBX changes with a preview before apply, the audit trail, undo, and the Echo box that answers questions from this server’s own data |
| 📡 Signaling capture | PBX settings → Signaling | What res_hep sends to the local aipbx-signaling daemon, the pbx_signaling_events table, and retention (off by default) |
| 📮 Voicemail | PBX settings → Voicemail | Mailboxes, listening (*97/*98, portal, apps, e-mail), message limits and PIN rules |
| 📈 Call quality | Reports → Call quality | Packet loss in both directions and jitter per trunk and extension from RTCP; a health check alarms when audio is lost |
📱 Mobile apps
The 🤖 Android and 🍎 iOS apps are built by GitHub Actions and attached to each GitHub Release. Users sign in with their portal username and password (plus 2FA when enabled), by scanning the QR code on My Phone, or with the link in their invitation e-mail.
🗺️ Roadmap & Specifications
| Page | What it covers |
|---|---|
| 📜 SDD Guide & Constitution | Specification-Driven Development (SDD) guide, core architectural rules (zero regressions, circuit breakers, pure generators), and living specifications index (Specs 001, 002, 003) |
| 🗺️ Roadmap | Planned work across future waves with detailed requirements and milestone criteria |
Planned work (website call widget, chat message deletion, S3 storage, video calls, local AI models, busy lamps on desk phones, phone provisioning, DHCP/TFTP …) with a short explanation of each: Roadmap.