Skip to main content

OpenAI

This guide outlines the steps required to configure the OpenAI Speech to Text API (Whisper) for use with the FS PBX voicemail transcription service.

OpenAI uses a modern and straightforward API Key for authentication. The underlying model, Whisper, is highly accurate and supports a wide range of languages.

Prerequisites​

  • An OpenAI account. You can create one at platform.openai.com.
  • Important: The OpenAI API is a paid service. You must have an active payment method on file in your OpenAI account's billing settings for the API to function.

Step 1: Create an OpenAI API Key​

First, you must generate a secret API key from your OpenAI account dashboard.

  1. Log in to the OpenAI Platform: Navigate to https://platform.openai.com/ and log in.

  2. Go to the API Keys Section:

    • Click on your profile icon or organization name in the top-right corner.
    • Select View API keys from the dropdown menu.

  3. Generate a New Key:

    • Click the + Create new secret key button.
    • Give the key a descriptive name, for example, fspbx-voicemail-transcription.
    • Click Create secret key.

  4. Copy and Save Your Key:

    • Your new API key will be displayed in a popup. Copy this key immediately and save it somewhere secure, like a password manager.

Security Warning: For your security, OpenAI will only show you the secret key one time. If you lose the key, you will need to delete it and create a new one. Treat this key like a password and do not commit it to public version control.

Step 2: Configuration​

Now, we will configure FS PBX to use your new OpenAI API key.

1. Update Environment Variables (.env)​

Add the following line to your .env file and populate it with the secret key you just copied.

# --- OPENAI SPEECH-TO-TEXT (WHISPER) CREDENTIALS ---
OPENAI_API_KEY="sk-YourSecretApiKeyCopiedFromOpenAI"

2. Optional: Select a Transcription Model​

FS PBX allows you to choose between different OpenAI Whisper models to balance cost, speed, and accuracy. This setting can be found in the user interface under Default Settings -> Voicemail by modifying the openai_transcription_model value.

The available models are:

  • whisper-1 (Default): The original, high-quality Whisper model. A great balance of speed and accuracy.
  • gpt-4o-transcribe: The latest and most advanced model, offering the highest transcription accuracy.
  • gpt-4o-mini-transcribe: A newer, more efficient model that provides faster and cheaper transcriptions, suitable for scenarios where speed is more critical than maximum accuracy.

3. Clear Configuration Cache​

To ensure the application loads the new environment variable, run the following commands from the terminal on your PBX server:

cd /var/www/fspbx
php artisan config:cache
php artisan queue:restart

Step 3: Activate the OpenAI Transcription Provider​

Note: For all new installations of FS PBX, the transcription provider is set to openai by default. You may only need to perform this step if you have changed it to another provider or wish to confirm the setting.

  1. In the FS PBX interface, navigate to the Default Settings section and then select Voicemail.
  2. Locate the setting named transcribe_provider.
  3. Ensure its value is set to openai.
  4. Save any changes.

Troubleshooting​

Checking the Logs​

The first place to check for any transcription issues is the main FS PBX log file.

The log is located at: /var/www/fspbx/storage/logs/laravel.log

To watch the log file for new errors in real-time, open a terminal on your PBX server and run the following command. Leave this command running while you trigger a new voicemail transcription. Any errors generated by the process will appear in your terminal instantly.

tail -f /var/www/fspbx/storage/logs/laravel.log

Error: 401 Unauthorized​

This error indicates a problem with your API key.

  • Cause 1: The OPENAI_API_KEY in your .env file is incorrect, has a typo, or is missing entirely. Double-check that it was copied correctly.
  • Cause 2: The key may have been revoked or deleted in the OpenAI dashboard.

Error: 429 You exceeded your current quota / Rate limit reached​

This error is related to billing and usage limits, not an incorrect key.

  • Cause 1: You do not have a valid payment method on file in your OpenAI account. Free trial credits may have expired or do not apply to this API usage.
  • Cause 2: Your payment method may have failed, or you have hit a monthly spending limit that you configured in your OpenAI billing settings.
  • Cause 3: Your account has reached its organizational rate limit. Log in to your OpenAI account and check your Billing and Usage sections to diagnose the issue.