(800) 862-5965
My Account
Network Status
View Categories

Adventures in Voicemail Transcripts

10 min read

Contents

Two ways to add speech-to-text to your FreePBX voicemail: the easy way, and the fun way.

If you have ever read a computer transcribed voicemail, you know the results can range from utterly unintelligible to downright hilarious. But you can usually glean just enough from a transcript to know whether a message is worth listening to, which is the whole point. As a bonus, you can identify which of your colleagues are secretly robots from another planet by their suspiciously perfect transcripts.

This article originally covered IBM’s Watson Speech-to-Text service. Watson’s Bluemix-era setup has since gone the way of the dodo, so we have updated the do-it-yourself portion to use Google Cloud Speech-to-Text. We have also added something that did not exist when we first wrote this: a supported, point-and-click option from Sangoma.

The Easy Way: Sangoma Scribe #

Scribe for FreePBX is Sangoma’s commercial AI transcription add-on for FreePBX and PBXact. You install the module, activate the license, and you are transcribing. No shell access, no API keys, no shell scripts intercepting your mail stream.

Scribe goes well beyond plain transcription:

  • Transcription of both voicemails and call recordings
  • Call summarization, so you get the gist without replaying the whole recording
  • Sentiment analysis per caller and per conversation
  • Tags and keyword alerts, including email notifications when a call contains certain keywords
  • Rewind, which transcribes your existing historical recordings and voicemails
  • Multi-language support
  • Audio file upload for meetings, interviews, and training sessions
  • Email integration and integration with CDR Pro, Call Recording Reports, and Softphones

Pricing at the time of writing is $24.99 per month, which includes 1,000 minutes of processed audio. Check the Scribe product page for current pricing, and the user guide for setup details.

Scribe pros

  • Supported by Sangoma. If it breaks, there is someone to call.
  • Installs and configures from the FreePBX GUI. No SSH required, which matters a great deal if you are on one of our Managed Server or Full Service plans.
  • Survives upgrades. Module updates are handled through the normal FreePBX update process.
  • Covers call recordings, not just voicemail.
  • Summaries, sentiment, tags, and keyword alerts are genuinely useful features you are not going to hand-roll over a weekend.
  • Predictable monthly cost.

Scribe cons

  • It costs $24.99 per month whether you transcribe 5 minutes or 1,000.
  • Audio leaves your system for processing by Sangoma’s service. Every transcription option in this article does this, but with Scribe you are choosing Sangoma as the processor rather than picking one yourself.
  • It is a commercial module, so it is not going to appeal to the “I run open source because I can see the source” crowd.

If you want transcription to just work, stop reading here and go buy Scribe. Seriously. The rest of this article is for people who enjoy this sort of thing.

The DIY Way: Google Cloud Speech-to-Text #

Still here? Good.

The DIY approach uses a shell script that sits between Asterisk’s voicemail system and sendmail. Asterisk hands the outbound notification email to the script instead of to sendmail directly. The script pulls the WAV attachment out of the message, converts it to FLAC, ships it to Google’s Speech-to-Text API, pastes the resulting text into the message body, converts the attachment to MP3 to save space, and then hands the whole thing off to sendmail.

The script is tony722’s sendmail-gcloud, which descends from Nicolas Bernaerts’ original sendmailmp3 by way of several community revisions. It is actively maintained and has been updated for FreePBX 17 and Debian.

DIY pros

  • Cheap. Google gives you 60 free minutes of transcription per month, and the enhanced phone call model runs roughly $0.024 per minute after that. A small office might never pay a dime.
  • You can see exactly what the script does and change it. Want a different language, punctuation settings, profanity filtering, or multiple language codes? Edit one line.
  • No commercial module license required.
  • It is a fun afternoon project if you like shell scripts.

DIY cons

  • Voicemail only. Call recordings are not covered.
  • Transcripts are capped at 59 seconds of audio. The script trims the FLAC file because the synchronous Google API rejects anything over a minute. Long messages get truncated transcripts.
  • No summaries, no sentiment analysis, no tags, no dashboard. Just text pasted into the email body.
  • Requires root SSH access. Our Managed Server and Full Service customers do not have shell access, so this is a Self-Managed option only. If you are on a managed plan and want transcription, Scribe is your path.
  • Your audio still leaves the box. Doing it yourself does not make it private. Every voicemail gets converted to FLAC and uploaded to Google Cloud for processing. You are trading one third-party processor for another, and you are now the one responsible for the data processing agreement, the data logging opt-in setting, and any compliance questions that come with it.
  • You own the breakage. FreePBX upgrades, OS upgrades, gcloud CLI changes, and Google API deprecations are all your problem. The script uses the V1 Speech-to-Text API via gcloud ml speech, which is the older of Google’s two APIs.
  • Your Google Cloud billing account has to stay healthy. If a card expires, transcription silently stops working.
  • You are inserting a script into the mail path for every voicemail notification on the system. See the warning below.

Before You Start: The Mail Command Warning #

Both approaches are worth trying. But understand what the DIY method actually does before you do it.

Both methods involve changing your Voicemail Admin mail command, and that setting is the single point of failure for all voicemail-to-email on your PBX.

Here is the default:

/usr/sbin/sendmail -t

When you point that at a custom script, every voicemail notification on the system flows through that script. If the script is missing, not executable, owned by the wrong user, or throws an error partway through, your users do not get a transcript-free email. They get no email at all, and they will probably not notice until someone asks why you never returned their call.

If you back out of either solution, you must set the mail command back to /usr/sbin/sendmail -t and apply changes. Removing the script, uninstalling the module, or letting your Google billing lapse without reverting this setting will break voicemail-to-email. Write it down somewhere before you begin.

Same goes for the attachment settings. Transcription requires that voicemail emails include the audio attachment, since the script works on the attached WAV. If you later disable attachments, the script has nothing to transcribe.

What Google Actually Heard #

Here is our standard test, spoken clearly and at an even pace:

What we said: “Hello, this is Nate from freepbxhosting.com testing Google’s transcription capabilities. Please call me back when you get this at 414-555-1234. Thanks!”

What Google heard: “Hello, this is Nate from free PBX hosting.com testing Google Transcription capabilities. Please call me back when you get this at 414 555 1234. Thanks.”

Not bad. Google handled the phone number correctly as digits, which is the thing that matters most in a voicemail. It stumbled on an uncommon proper noun, as every engine does. Your results will vary, sometimes significantly and often hilariously.

The Procedure #

These steps target FreePBX 17 on Debian 12. Notes for FreePBX 16 on Sangoma Linux 7 follow where the commands differ. Take a backup before you start.

Step 1: Set up Google Cloud #

  1. Create a Google Cloud account if you do not have one. New accounts get a free trial credit.
  2. Create a project and make note of the Project ID.
  3. Search the console for Cloud Speech-to-Text API and enable it on that project.
  4. Enable billing on the project. The free 60 minutes per month still requires a payment method on file.
  5. Create a service account and download its JSON key. Recent versions of the API will not authenticate with a plain user account. See Google’s service account documentation.

Step 2: Install dependencies #

Install the Google Cloud CLI by following steps 1 through 3 of Google’s Debian install instructions, then install the supporting tools:

apt update
apt install -y jq sox flac dos2unix lame

FreePBX 16 / Sangoma Linux 7: use the RPM repo instructions instead and install with yum install -y google-cloud-cli jq sox flac dos2unix lame.

Verify that sox can actually write FLAC. Some minimal installs ship sox without FLAC support, which produces an empty transcript with no obvious error:

sox --help | grep -i flac

Step 3: Install the script #

Copy the contents of the gist to /usr/sbin/sendmail-gcloud, then:

cd /usr/sbin/
chown asterisk:asterisk sendmail-gcloud
chmod 744 sendmail-gcloud

A note on permissions: some older versions of these instructions told you to chmod 777 /usr/bin/dos2unix. Do not do that. A world-writable binary in a system path is a privilege escalation waiting to happen. Stock dos2unix is installed 755 and root-owned, which means it is already executable by the asterisk user and no change is needed.

Step 4: Authenticate as the asterisk user #

The script runs as asterisk, so the gcloud credentials have to live in the asterisk user’s home directory.

su asterisk
gcloud auth activate-service-account YOUR-SERVICE-ACCOUNT@your-project.iam.gserviceaccount.com --key-file=/path/to/key.json
gcloud config set project "Your Project ID"

Setting the project is not optional. Skipping it is the most common cause of the dreaded “Google was unable to recognize any speech in audio data” message.

On some builds the asterisk account is set to nologin and su asterisk will fail. Temporarily give it a shell with usermod -s /bin/bash asterisk, authenticate, then set it back with usermod -s /usr/sbin/nologin asterisk.

Confirm the credentials landed where the script expects them:

ls -la /home/asterisk/.config/gcloud

That path is hard-coded in the script as CLOUDSDK_CONFIG. If your credentials are somewhere else, either move them or edit that line.

Step 5: Configure FreePBX #

  1. In the GUI, go to Settings > Voicemail Admin > Settings.
  2. On the Settings tab, set the format field to wav|wav49.
  3. On the Email Config tab, set Mail Command to /usr/sbin/sendmail-gcloud.
  4. Make sure voicemail email attachments are enabled, either globally here or per extension.
  5. Click Submit, then Apply Config.

Step 6: Test #

Leave yourself a voicemail. Within a few seconds of hanging up you should get an email with the usual notification, an MP3 attachment, and a new section reading:

--- Google transcription result ---

If you got an email with no transcript, or no email at all, move on to troubleshooting.

Troubleshooting #

No email arrives at all. The script failed before reaching sendmail. Revert the mail command to /usr/sbin/sendmail -t, apply changes to restore service, then debug offline. Uncomment the two debug lines at the top of the script to capture stderr to /tmp/sendmail-gcloud-debug.log.

Email arrives, transcript says Google could not recognize any speech. Usually an authentication or project problem. Run the gcloud command by hand as the asterisk user against a known-good FLAC file and read the actual error. Also check that your billing account and trial credit have not lapsed, which produces the same unhelpful message.

Transcript stops partway through long messages. Expected. The script trims audio to 59 seconds because the synchronous API rejects longer input. If you want full transcripts, swap gcloud ml speech recognize for gcloud ml speech recognize-long-running and drop the trim 0 59 from the sox line. Be aware that this adds latency and that long-running recognition may require staging the audio in Cloud Storage.

MP3 attachment will not play. Check that lame is installed and that the sox conversion is producing a valid intermediate WAV.

Everything worked, then stopped after an upgrade. FreePBX and OS upgrades can overwrite /usr/sbin/sendmail-gcloud or reset the mail command. Check both after every major upgrade.

Tweaks Worth Knowing About #

The transcription line in the script is where most of the interesting customization lives:

gcloud ml speech recognize stream.part3.flac --language-code='en-US' --model=phone_call --filter-profanity --enable-automatic-punctuation
  • --model=phone_call uses Google’s telephony-tuned model, which is meaningfully better on 8kHz audio than the default. Some users prefer phone_call_enhanced.
  • --enable-automatic-punctuation is the difference between a wall of words and something readable.
  • --filter-profanity does what it sounds like. Remove it if you want the unvarnished truth.
  • --additional-language-codes lets you handle multilingual callers, though results get unpredictable when a message starts in one language and continues in another.

Backing Out #

Whichever route you take, if you decide transcription is not for you:

  1. Go to Settings > Voicemail Admin > Settings > Email Config.
  2. Set Mail Command back to /usr/sbin/sendmail -t.
  3. Click Submit, then Apply Config.
  4. Send yourself a test voicemail and confirm the email arrives.

Only after you have confirmed that working email should you remove the script, delete the service account, or cancel the module. Reversing that order is how you end up with a week of silently lost voicemail notifications.

Which Should You Choose? #

If you are on our Managed Server or Full Service plans, Scribe is the answer, since those plans do not include shell access. It is also the answer for anyone who bills by the hour and would rather not spend those hours on a shell script.

If you are Self-Managed, comfortable in Linux, transcribing a modest volume of voicemail, and you enjoy tinkering, the Google route costs almost nothing and works well within its limits.

Either way, write down the default mail command before you touch anything.

Credits and acknowledgements