Convert voicemail audio to text using OpenAI's Whisper model. Runs on a separate server, supports multiple PBX systems, and delivers transcriptions straight to email — no commercial licenses required.
Two-component architecture: a lightweight script on each PBX, and a central transcription server.
A custom mail command (vm-mailcmd-stt.py) replaces FreePBX's default voicemail handler. When a voicemail arrives, it sends the audio file to the STT server via HTTP instead of emailing it directly.
Config: /etc/whisper-mailcmd.json
A FastAPI server receives uploads and places them in a file-based queue. A background worker picks up jobs, transcribes the audio using faster-whisper, and emails the transcript to the voicemail recipient.
Config: /opt/whisper-stt/api/config.json
| Component | Version |
|---|---|
| FreePBX | 15, 16, or 17 (or vanilla Asterisk) |
| Python | 3.x (for the mail command script) |
| Access | Ability to modify Voicemail Admin settings |
| Component | Version |
|---|---|
| OS | Oracle Linux 9.5 |
| Python | 3.9+ |
| ffmpeg | Latest |
| faster-whisper | Latest |
Two quick installs — one on the STT server, one on each PBX.
Installs all dependencies, sets up the Python venv, configures systemd services, creates queue directories, and configures msmtp.
Edit /opt/whisper-stt/api/config.json to set your allowed networks, authentication token, Whisper model size, and sender email address.
Installs the custom mail command script and generates the initial configuration file.
In FreePBX Admin → Settings → Voicemail Admin:
To: ${VM_MAILBOX}/usr/local/sbin/vm-mailcmd-stt.pyEdit /etc/whisper-mailcmd.json to set the STT server endpoint, authentication token, and whether to include the original voicemail email body.
Verify your setup with a simple curl command.
A successful response returns: {"status":"queued","job_id":"JOB-xxx","message":"Voicemail accepted."}
Full documentation is included in the repository:
architecture.md — System design and workflowtroubleshooting.md — Common issues and fixesfreepbx-voicemail-admin.md — FreePBX configurationtesting-with-curl.md — Testing methodologyemail-configuration.md — msmtp and email setupReleased under the MIT License. Use it, modify it, deploy it — no restrictions, no license fees, no phone-home.
Get It on GitHub