AiPBX
Features Install Videos Mobile Docs Live demo Contact Sponsor on GitHub UpCloud ($250 Free Credit) YouTube GitHub
ODOO Connect AiPBX with Odoo CRM & ERP — manage calls & customers in one place. Try Odoo Free →
Home / Documentation / AiPBX Documentation

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.

🖥️ Live demo: aipbx.bid/demo shows every page of the portal with made-up data, without installing anything.

💡 Quick Diagnosis: When something does not work, start with the 🗺️ system map (where everything is) and 🛠️ troubleshooting (symptom → fix).

🚀 Getting started

PageWhat it covers
🚀 Installation & updatingRequirements, one-line installer, certificates, ports, aipbx-update
📦 Incus or LXD containerRunning the normal install in a system container, networking, snapshots
📺 Video: InstallationStep-by-step setup on YouTube: English · Türkçe · Deutsch
📺 Video: Menu tourEvery screen of the portal on YouTube: English · Türkçe · Deutsch
🖥️ Portal basicsThe Apply workflow, edit dialogs, ordering lists, copying records
💾 Backups, recovery & rollbackReproducible daily backups (aipbx-backup), disaster recovery restore commands, and zero-downtime automated upgrade rollback (aipbx-update)
🛠️ CLI & Server commandsTerminal utilities (aipbx-update, aipbx-backup, aipbx-restore, aipbx-selftest, aipbx-cert, SSO recovery)
🏗️ ArchitectureComponents, traffic flow, security model

📞 Telephony

PageWhat it covers
🌐 TrunksConnection modes, inbound DID trimming, transit routing, outbound caller ID normalization, copy / rename / order
🚫 Blacklist & Spam blockerInbound spam blocking, AstDB sub-microsecond lookup, wildcards/patterns, drop/busy/congestion/announcement actions
📤 Outbound routesDial patterns, number manipulation, trunk failover, route groups, RFC 6442 / RFC 6443 Geolocation emergency headers
🎛️ Outbound and inbound call normalizationRules for dialled numbers per device (mobile, desk, web), rules for incoming numbers per trunk, ready-made rules per country, E.164, SIP headers
📥 Inbound routes (DIDs)DID matching, destinations, fax DIDs
⚙️ PBX SettingsEvery tab of System → PBX Settings and where each is explained
📟 ExtensionsThe extension form, copying a SIP password, per-extension SIP settings (transport, DTMF, SRTP, NAT, codecs)
🛣️ TransportsWhere Asterisk listens for SIP: ports, TCP and TLS, your own transports
🎛️ Advanced ConfigurationYour own Asterisk options, objects and file text that survive regeneration and updates, versions, generated files changed by hand
📠 Fax users and numbersFax Units, the number a fax goes out with, several and shared numbers, Fax Settings, who can delete
📠 Fax cover pageOne cover template for the organisation, logo, preview as a fax
🔢 How numbers change on a callThe order of every number setting on routes, trunks and normalization pages, with a diagram
💻 Custom DialplanCustom Asterisk context injection, syntax validator, internal aggregator, recipe templates (Intercom, Spy, Paging, DISA)
☎️ Desk phonesProvisioning 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, regions, SIP over TLS on port 443
📒 PhonebookShared company contacts, LDAP phonebook for desk phones (name search, caller name), contacts from Active Directory / OpenLDAP with the ldap-sync plugin
🔵 Cisco 7900 / 8800 seriesCisco'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 settingsThe server's network cards, and moving every address after an IP change in one step
🔐 VPN server and clientWireGuard or OpenVPN: let phones and laptops reach the PBX through a tunnel (including Yealink OpenVPN .tar packages with vpn.cnf + keys), and connect the PBX to another network by uploading a profile
🛡️ Reverse proxy setupDeploying behind Nginx, Caddy, Traefik, HAProxy, Apache; WebRTC WebSocket proxying, trusted proxies, and SIP/RTP bypass
📡 Network servicesDHCP (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 checksThe server watches itself (services, trunks, disk, certificate, backup …), alarm e-mails, the daily summary with yesterday's calls, aipbx-selftest
🎙️ Call recordingsWhere recordings live, automatic MP3 conversion, playback
🎧 Queues and the agent screenQueue setup, static and dynamic agents, breaks, waiting calls and manual callbacks
☎️ Manual queue callbacksPress 1 while waiting, confirmation announcement, agent callback list, automatic removal after a conversation, troubleshooting
📊 ReportsCall reports with trunks and direction, Queue Report Centre, PDF and Excel export
🔊 Sounds & languagesCustom sounds, the Turkish prompt packages (six formats), regenerating a prompt
🌍 TranslatingInterface languages, adding or correcting a translation with scripts/i18n.py, mobile app texts, prompts in other languages
📹 Video callsVideo between the web phone, the Android app and desk video phones; the one video codec; bandwidth
🗓️ Video meetingsScheduled browser rooms, SFU/Follow-Talker, guest links, invitations, join windows and calendar downloads
🎧 WebRTC, NAT and TURNBrowser and app audio across NAT, external IP, TURNS on 443, troubleshooting silent calls
🗄️ External databases & IVR data stepsRead-only MySQL/PostgreSQL connections, encrypted credentials, real-time IVR caller/DTMF data lookups and call branching
🎚️ PBX fine tuning & maintenanceJitter buffer, SIP protocol timers (T1, B, Max-Forwards), 10-minute SIP debug, safe night restart window, spoken status messages
🐧 Linux OS & kernel tuningNetwork sysctl (RTP buffers, MPTCP disable), SIP ALG blacklist, real-time CPU scheduling, OOM protection, needrestart shielding

🔐 Users and security

PageWhat it covers
👥 Users & rolesAdding users and invitations, the admin account, built-in roles, permissions, My Phone
🛡️ SecurityFirewall (common and per-card rules), the Sign-in page (Security → Sign-in: sign-in check, sign-in alerts, SSO-only), fail2ban, the aipbx-priv root helper, Apache sandbox
🔒 Privileged job stateRoot-owned status, network rollback data and validated upload snapshots
📜 Privileged job logsRoot log ownership, portal read access and rotation
🖧 Network ports & firewallComplete matrix of all TCP/UDP ports, public vs LAN scopes, NAT guidelines, UFW/firewalld/iptables recipes
🛡️ Threat model & attack surfaceSecurity architecture, SIP exposure boundaries, WebRTC/TURNS credentials, recording retention, mobile push tokens, and AI least privilege guardrails
⚖️ GDPR, KVKK & data privacyOptional 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
📜 CertificatesOne 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-mailMail relay and e-mail templates (fax, voicemail, invitations, password e-mails)
🗄️ File storageChat attachments on the local disk or in an S3-compatible bucket (AWS S3, MinIO, Wasabi, Backblaze B2), moving existing files
🔑 REST API v1 & outbound webhooksStateless /api/v1/* endpoints, OpenAPI 3.1 spec, Bearer API keys (apbx_...), scopes, IP allowlists, and HMAC-SHA256 signed webhooks
⏱️ Scheduled tasksSandboxed background shell, PHP and Python scripts on a cron schedule (aipbx-task, systemd-run), run history, bell alarms
🛠️ TroubleshootingThe Troubleshooting menu (SIP traffic .pcap/calls/ladder/live, problem recording, registrations, call quality, phone logs), changes not applied, calls hung up, sounds not found

🔌 Plugins

Optional integrations are enabled under Integration → Plugin Catalog (/plugins). Official plugins ship in AiPBX's plugins/ directory; community plugins are installed from the opt-in signed catalog or as uploaded ZIPs. See each guide for its minimum version and installation method:

PagePlugin slugWhat 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-authEnterprise 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-dialerAutomated outbound calling campaigns with Answering Machine Detection (AMD), queue free-agent pacing, voicemail drop, and CSV call results
🪪 Caller Name (CNAM) Lookup (Plugin)cnamInbound caller name lookup: local phonebook & extensions first, then BulkVS, Telnyx, Twilio, Vonage, OpenCNAM, SignalWire, NumVerify, AbstractAPI or Custom URL with 30-day cache
💬 SMS & MMS Messaging (Plugin)smsTwo-way text and multimedia messaging via Twilio, Vonage, Plivo, Telnyx, Bandwidth, Sinch, VoIP.ms or BulkVS with multi-user team inboxes, contacts, and SSRF-shielded attachments
🎙️ AI Voicemail Transcription & Summary (Plugin)ai-voicemailAutomated Whisper audio transcription and LLM executive summaries, urgency classification, action-item extraction, and PCI-DSS PII masking
🌐 SIP Provider Templates (Plugin)provider-templates1-click SIP trunk creation from community carrier profiles (Twilio, Telnyx, A1, Drei, etc.) with pre-configured PJSIP NAT, timers, and codec flags
🌐 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-voicemailAccounts 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-ttsText to speech with Google, Amazon Polly, Azure, ElevenLabs or OpenAI; saving announcements
🧠 Local AI models (Plugin)ai-modelsAI models on the PBX itself (EMA Lightning Turkish TTS): the runtime, downloading models, the aipbx-ai service and its API
🎛️ AI applications (Plugin)ai-appsAI features with their own numbers that take calls: announcements with values (caller, lookup address)
🛰️ External AI agentsAI → External agentsA voice agent of another service at a SIP address as a call destination; hand-over to a person by REFER, call limit, fallback
✨ Dialplan editor / AI assistant (Community plugin, @shido6)ai-assistantPlain-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 captureTroubleshooting → SIP capture settingsWhat res_hep sends to the local aipbx-signaling daemon, the pbx_signaling_events table, .pcap capture files, and retention (off by default)
📮 VoicemailPBX settings → VoicemailMailboxes, listening (\*97/\*98, portal, apps, e-mail), message limits and PIN rules
📈 Call qualityTroubleshooting → Call qualityPacket 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

PageWhat it covers
📜 SDD Guide & ConstitutionSpecification-Driven Development (SDD) guide, core architectural rules (zero regressions, circuit breakers, pure generators), and living specifications index (Specs 001, 002, 003)
🗺️ RoadmapPlanned work across future waves with detailed requirements and milestone criteria

The Roadmap distinguishes delivered features from proposals and larger future projects.

View or edit this page on GitHub

On This Page