FreePBX Asterisk Voicemail Transcription Module

FreePBX 17 Voicemail Transcription

Alpha Computer Group Voicemail Transcription adds opt-in voicemail speech-to-text to FreePBX 17 while keeping transcription work outside of the live Asterisk call path. Voicemail recording and normal PBX call processing do not wait for Whisper to finish.

Module version: 17.0.2
Publisher: Alpha Computer Group
Platform: FreePBX 17 / Asterisk / Debian 12
License: GPLv3+
Architecture: FreePBX PBX-side module + separate whisper.cpp transcription server

What the Module Installs

Version 17.0.2 is the complete PBX-side package. Installing it through FreePBX Module Admin deploys the per-extension controls, asynchronous voicemail mail queue, transcription client, MP3 conversion integration, deadline watchdog, crash-recovery logic, systemd units, persistent configuration files, and the Asterisk voicemail mail wrapper.

The speech-to-text engine itself is intentionally not installed on the PBX. Whisper runs on a separate Linux or Windows server so CPU/GPU transcription work cannot compete with Asterisk call processing.

Default-Off Behavior

Every extension is disabled by default. An extension must be explicitly enabled before its voicemail audio is sent to the transcription server.

• Disabled extension: no AI request.
• Disabled extension: no VOICEMAIL TRANSCRIPTION heading.
• Disabled extension: no transcript.
• Disabled extension: no “transcription unavailable” message.
• Disabled extension: no transcription disclaimer.
• The normal voicemail email and audio attachment continue normally.

PBX Installation Through FreePBX Module Admin

1. Download the .tgz package above.
2. Log in to FreePBX Administration.
3. Open Admin > Module Admin.
4. Choose Upload Modules.
5. Upload the TGZ.
6. Install and enable Voicemail Transcription.
7. Open Settings > Voicemail Transcription.
8. Enter the transcription server URL and save the global settings.
9. Open Applications > Extensions, edit an extension, and explicitly enable Voicemail Transcription only for the users who should receive transcripts.

The module does not restart Asterisk. During installation it updates the FreePBX voicemail mailcmd to the asynchronous wrapper and requests an Asterisk voicemail configuration reload.

PBX Requirements

The PBX-side installer expects Python 3, systemd, the FreePBX Voicemail module, and a working /usr/sbin/sendmail-compatible local mail interface. ffmpeg at /usr/bin/ffmpeg is strongly recommended so voicemail attachments can be converted to MP3. The module does not automatically install operating-system packages.

PBX Files and Settings

/etc/pbx-transcription.ini
/etc/pbx-transcription-extensions.ini
/var/lib/asterisk/pbx-transcription/extensions.ini
/var/spool/pbx-vm-mail/
/usr/local/sbin/sendmailmp3
/usr/local/libexec/pbx-vm-transcribe
/usr/local/libexec/pbx-vm-mail-worker
/usr/local/libexec/pbx-vm-queue-runner
/usr/local/libexec/pbx-vm-deadline-watchdog

The per-extension state file contains only extensions that are explicitly enabled:

[extensions]
442 = true
555 = true

An extension that is not listed is treated as Disabled.

Configure the PBX to Reach the Transcription Server

After the Linux or Windows transcription server is running, go to Settings > Voicemail Transcription and configure a URL such as:

http://TRANSCRIPTION-SERVER-IP:8765/inference

Recommended starting settings:

Global backend: Enabled
Connect timeout: 5 seconds
Maximum AI time: 200 seconds
Temperature: 0.0

The global switch only enables the backend. It does not opt in extensions. Each extension still has to be individually enabled.

---

Linux Transcription Server Installation

This example uses Ubuntu Server or Debian and builds whisper.cpp v1.9.2 from source. It uses the English medium.en model and CPU inference. A GPU is optional; the FreePBX module only requires a compatible HTTP /inference endpoint.

1. Install Build Requirements

sudo apt update
sudo apt install -y git cmake build-essential curl ca-certificates ffmpeg

2. Create a Dedicated Service Account

sudo useradd --system --home /opt/whisper.cpp --shell /usr/sbin/nologin whisper 2>/dev/null || true

3. Download and Build whisper.cpp v1.9.2

sudo git clone --branch v1.9.2 --depth 1 https://github.com/ggml-org/whisper.cpp.git /opt/whisper.cpp
sudo cmake -S /opt/whisper.cpp -B /opt/whisper.cpp/build -DCMAKE_BUILD_TYPE=Release
sudo cmake --build /opt/whisper.cpp/build -j "$(nproc)" --config Release

4. Download the medium.en Model

cd /opt/whisper.cpp
sudo sh ./models/download-ggml-model.sh medium.en
sudo chown -R whisper:whisper /opt/whisper.cpp

5. Test the Server Manually

sudo -u whisper /opt/whisper.cpp/build/bin/whisper-server \
  --model /opt/whisper.cpp/models/ggml-medium.en.bin \
  --host 0.0.0.0 \
  --port 8765 \
  --threads 4 \
  --processors 1 \
  --language en \
  --no-gpu \
  --no-timestamps

Leave that terminal open and, from another terminal on the transcription server, test the HTTP inference endpoint:

curl -sS http://127.0.0.1:8765/inference \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/opt/whisper.cpp/samples/jfk.wav" \
  -F "temperature=0.0" \
  -F "response_format=json"

You should receive JSON containing the recognized speech.

6. Run whisper.cpp Automatically with systemd

Create /etc/systemd/system/pbx-whisper.service:

[Unit]
Description=PBX Whisper Transcription Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=whisper
Group=whisper
WorkingDirectory=/opt/whisper.cpp
ExecStart=/opt/whisper.cpp/build/bin/whisper-server --model /opt/whisper.cpp/models/ggml-medium.en.bin --host 0.0.0.0 --port 8765 --threads 4 --processors 1 --language en --no-gpu --no-timestamps
Restart=always
RestartSec=10
Nice=10
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target

Then enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now pbx-whisper.service
sudo systemctl status pbx-whisper.service --no-pager

7. Restrict Port 8765

Do not expose the Whisper upload endpoint broadly to the Internet. Permit TCP 8765 only from the FreePBX server or a trusted private network. If the Linux host uses UFW, an example is:

sudo ufw allow from YOUR-PBX-IP to any port 8765 proto tcp

Replace YOUR-PBX-IP with the actual source address that the transcription server sees.

Optional NVIDIA CUDA Build

If the Linux transcription server has a supported NVIDIA GPU and a working CUDA toolkit, rebuild whisper.cpp with CUDA enabled:

sudo cmake -S /opt/whisper.cpp -B /opt/whisper.cpp/build-cuda -DGGML_CUDA=1 -DCMAKE_BUILD_TYPE=Release
sudo cmake --build /opt/whisper.cpp/build-cuda -j "$(nproc)" --config Release

Then point the systemd ExecStart to the CUDA build and remove --no-gpu. Test the GPU build before changing a production service.

---

Windows Transcription Server Installation

This example uses the official whisper.cpp v1.9.2 Windows x64 prebuilt package and the medium.en model. Run PowerShell as Administrator for the installation steps.

1. Create the Installation Directory

$Root = 'C:\PBX-Transcription\whispercpp'
New-Item -ItemType Directory -Path $Root -Force | Out-Null

2. Install the Microsoft Visual C++ Runtime

The official Windows binaries may require the Microsoft Visual C++ 2015-2022 x64 runtime.

$VcRedist = "$env:TEMP\vc_redist.x64.exe"
curl.exe -L --fail "https://aka.ms/vs/17/release/vc_redist.x64.exe" -o $VcRedist
Start-Process -FilePath $VcRedist -ArgumentList '/install','/quiet','/norestart' -Wait

If Windows reports restart code 3010, complete a maintenance reboot before relying on the service in production.

3. Download whisper.cpp v1.9.2 x64

$Zip = "$env:TEMP\whisper-bin-x64-v1.9.2.zip"
curl.exe -L --fail "https://github.com/ggml-org/whisper.cpp/releases/download/v1.9.2/whisper-bin-x64.zip" -o $Zip

Get-FileHash $Zip -Algorithm SHA256

Expand-Archive -Path $Zip -DestinationPath $Root -Force

The SHA-256 of the official v1.9.2 whisper-bin-x64.zip package used by this guide is:

49dcc16de826f20bd53d44f947a1ae49dfa81f86cad67a64d80820cb192d674a

Confirm that the server executable exists:

Get-ChildItem -Path $Root -Filter whisper-server.exe -Recurse | Select-Object FullName

The tested x64 package layout normally places it under:

C:\PBX-Transcription\whispercpp\bin\Release\whisper-server.exe

4. Download the medium.en Model

$ModelDir = Join-Path $Root 'models'
New-Item -ItemType Directory -Path $ModelDir -Force | Out-Null

$Model = Join-Path $ModelDir 'ggml-medium.en.bin'
curl.exe -L --fail "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.en.bin" -o $Model

Get-Item $Model | Select-Object FullName,Length

5. Start the Server Manually

$Exe = 'C:\PBX-Transcription\whispercpp\bin\Release\whisper-server.exe'
$Model = 'C:\PBX-Transcription\whispercpp\models\ggml-medium.en.bin'

& $Exe `
  --model $Model `
  --host 0.0.0.0 `
  --port 8765 `
  --threads 4 `
  --processors 1 `
  --language en `
  --no-gpu `
  --no-timestamps

Keep the PowerShell window open while testing. From another PowerShell window on the same server, confirm that TCP 8765 is listening:

Get-NetTCPConnection -LocalPort 8765 -State Listen

6. Create a Startup Command File

Create C:\PBX-Transcription\whispercpp\run-whisper.cmd with:

@echo off
cd /d C:\PBX-Transcription\whispercpp
start "" /belownormal /wait "C:\PBX-Transcription\whispercpp\bin\Release\whisper-server.exe" --model "C:\PBX-Transcription\whispercpp\models\ggml-medium.en.bin" --host 0.0.0.0 --port 8765 --threads 4 --processors 1 --language en --no-gpu --no-timestamps

For production, run this startup command through Task Scheduler or your normal Windows service-management tooling under a dedicated, low-privilege service identity. Configure it to start at boot and restart if the process exits. Avoid giving an upload-processing service unnecessary administrative privileges.

7. Restrict the Windows Firewall Rule to the PBX

Replace YOUR-PBX-IP before running:

New-NetFirewallRule `
  -DisplayName 'PBX Whisper TCP 8765' `
  -Direction Inbound `
  -Action Allow `
  -Protocol TCP `
  -LocalPort 8765 `
  -RemoteAddress YOUR-PBX-IP

Do not create an unrestricted Internet-facing rule for TCP 8765.

Optional Windows NVIDIA GPU

whisper.cpp publishes CUDA-capable Windows packages for supported NVIDIA environments. GPU builds can dramatically reduce transcription time, but CUDA driver/toolkit compatibility must be validated on the specific server. Start with the CPU package above, prove the complete voicemail flow, and then move to a GPU build if required.

---

Test the Transcription Server Before Connecting FreePBX

whisper.cpp exposes /inference as its default inference path. A multipart request should return JSON. On Linux:

curl -sS http://127.0.0.1:8765/inference \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/opt/whisper.cpp/samples/jfk.wav" \
  -F "temperature=0.0" \
  -F "response_format=json"

After local testing succeeds, test TCP reachability from the FreePBX server to the transcription server:

curl -I --connect-timeout 5 http://TRANSCRIPTION-SERVER-IP:8765/

A response from the HTTP server proves network reachability even if the root URL returns a non-inference page or HTTP status. The actual voicemail integration uses /inference.

Configure FreePBX

1. Open Settings > Voicemail Transcription.
2. Set the URL to http://TRANSCRIPTION-SERVER-IP:8765/inference.
3. Set the global backend to Enabled.
4. Save the settings.
5. Use the server-connection test on the page.
6. Open Applications > Extensions.
7. Edit only the extension or extensions that should receive transcripts and set Voicemail Transcription to Enabled.

How Email Delivery Works

Asterisk hands the voicemail email to the local queue wrapper immediately. The queue worker checks whether the destination extension is opted in. If it is disabled, the worker bypasses AI and sends the normal voicemail email. If it is enabled, the worker submits the audio to the external Whisper endpoint, adds the result to the email, and sends the recording as the authoritative attachment.

If the transcription server is unavailable or takes too long, the PBX-side deadline/recovery system is designed to release the voicemail email rather than wait indefinitely for AI. External SMTP/provider delivery time is outside the module’s internal processing window.

Verify PBX-Side Services

systemctl is-active pbx-vm-mail-queue.path
systemctl is-active pbx-vm-mail-deadline.timer
systemctl is-active asterisk

for D in incoming working deadline failed; do
    printf "%-9s " "$D:"
    find "/var/spool/pbx-vm-mail/$D" -maxdepth 1 -type f | wc -l
done

Normally the queue directories return to zero after each voicemail is processed.

Troubleshooting

Transcription Is Disabled but AI Text Appears

Check the extension state file:

cat /etc/pbx-transcription-extensions.ini

Only explicitly enabled extensions should appear as true. Missing extensions are disabled.

Voicemail Sends but There Is No Transcript

Confirm the global backend is enabled, verify the extension is opted in, test TCP connectivity to the transcription server, and verify that whisper-server is running and listening on TCP 8765.

MP3 Is Not Attached

Verify that /usr/bin/ffmpeg exists on the FreePBX server:

command -v ffmpeg
ffmpeg -version | head

Check the PBX Queue Log

journalctl -t sendmailmp3 -t pbx-vm-mail-queue -t pbx-vm-mail-deadline --since "-30 minutes" --no-pager

Security and Privacy

• Restrict the transcription server so only trusted PBX addresses can connect.
• Do not expose the raw whisper.cpp upload endpoint broadly to the public Internet.
• If voicemail audio crosses an untrusted network, place the endpoint behind TLS, a VPN, or another trusted encrypted transport.
• Run the transcription process with the least operating-system privilege practical.
• Treat voicemail audio and transcripts as potentially sensitive business information.
• Keep the voicemail recording available because automatic transcription can misinterpret names, numbers, dates, dollar amounts, and specialized terminology.

Uninstall and Upgrade Notes

The module records the previous FreePBX voicemail mail command and attempts to restore it during uninstall. Pre-existing unmanaged helper files are backed up before the module replaces them. Configuration, extension choices, and queue directories are intentionally preserved where practical so an upgrade or reinstall does not silently destroy state.

Because this is an independent local/third-party FreePBX module, Module Admin may display it as Unsigned and Not available online. Test new releases on a staging PBX before deploying them to a production phone system.

Upstream whisper.cpp References

whisper.cpp project
whisper.cpp HTTP server documentation
whisper.cpp v1.9.2 release

Support

For FreePBX implementation assistance, voicemail transcription integration, managed VoIP, or PBX support, contact Alpha Computer Group.

Alpha Computer Group