feat(audio): Enforce strict AI_API_BASE_URL and add FFmpeg MP3 STT conversion

apps/api/src/routes/ai.ts

@@ -3,6 +3,7 @@ import { aiService } from '../services/ai';
 import { PdfOnePagerRenderer } from '../services/renderers/pdf-renderer';
 import { PptxDeckRenderer } from '../services/renderers/pptx-renderer';
 import { uploadFile } from '../services/storage';
+import { convertToMp3IfNeeded } from '../services/ai/ffmpeg';
 import { z } from 'zod';
 
 
@@ -98,7 +99,8 @@ export async function aiRoutes(fastify: FastifyInstance) {
         const buffer = Buffer.from(audioBase64, 'base64');
 
         try {
-            const text = await aiService.transcribeAudio(buffer, filename);
+            const { buffer: audioToTranscribe, format } = await convertToMp3IfNeeded(buffer, filename);
+            const text = await aiService.transcribeAudio(audioToTranscribe, `message.${format}`);
             return { success: true, text };
         } catch (err: any) {
             if (err?.name === 'QuotaExceededError') {

apps/api/src/services/ai/ffmpeg.ts

@@ -0,0 +1,55 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { writeFile, readFile, unlink } from 'fs/promises';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+
+const execAsync = promisify(exec);
+
+/**
+ * Converts an audio buffer to MP3 using local FFmpeg if the file is OGG/OPUS.
+ * This ensures compatibility with OpenAI Whisper, which frequently rejects native WhatsApp OPUS files.
+ * Returns the original buffer if ffmpeg fails or isn't installed to attempt best-effort transcription.
+ */
+export async function convertToMp3IfNeeded(inputBuffer: Buffer, filename: string): Promise<{ buffer: Buffer; format: string }> {
+    // We only strictly convert OGG or OPUS files (which are typical for WhatsApp).
+    // If it's already an MP4/AAC or M4A, Whisper usually accepts it fine.
+    if (!filename.toLowerCase().endsWith('.ogg') && !filename.toLowerCase().endsWith('.opus') && !filename.toLowerCase().endsWith('.oga')) {
+        return { buffer: inputBuffer, format: filename.split('.').pop()! };
+    }
+
+    const tempId = randomBytes(8).toString('hex');
+    const inputPath = join('/tmp', `in_${tempId}_${filename}`);
+    const outputPath = join('/tmp', `out_${tempId}.mp3`);
+
+    try {
+        console.log(`[FFMPEG] Starting conversion for ${filename}...`);
+
+        // Write the inbound buffer to a temp file
+        await writeFile(inputPath, inputBuffer);
+
+        // Run FFmpeg to convert it to a standard 128k MP3
+        // -y overwrites without prompting
+        // -i specifies input file
+        // -vn disables video just in case
+        // -ar sets audio sample rate
+        // -ac sets channels to mono (perfect for voice)
+        // -b:a sets audio bitrate to 64k (sufficient for voice, saves bandwidth)
+        await execAsync(`ffmpeg -y -i "${inputPath}" -vn -ar 44100 -ac 1 -b:a 64k "${outputPath}"`);
+
+        // Read the converted file back into a buffer
+        const mp3Buffer = await readFile(outputPath);
+        console.log(`[FFMPEG] ✅ Successfully converted ${filename} to MP3.`);
+
+        return { buffer: mp3Buffer, format: 'mp3' };
+
+    } catch (err: any) {
+        console.error(`[FFMPEG] ⚠️ Conversion failed for ${filename}. Proceeding with original buffer. Error: ${err.message}`);
+        // If FFMPEG isn't installed or fails, we return the original buffer
+        return { buffer: inputBuffer, format: filename.split('.').pop()! };
+    } finally {
+        // Cleanup temp files asynchronously
+        unlink(inputPath).catch(() => { });
+        unlink(outputPath).catch(() => { });
+    }
+}

apps/whatsapp-worker/src/config.ts

@@ -2,10 +2,10 @@ import dotenv from 'dotenv';
 dotenv.config();
 
 /**
- * Normalizes a base URL by ensuring it starts with https:// 
- * and removing any trailing slashes.
+ * Strictly requires a base URL to start with https:// 
+ * and removes any trailing slashes.
  */
-export function normalizeBaseUrl(url: string | undefined, keyName: string): string {
+export function requireHttpUrl(url: string | undefined, keyName: string): string {
     if (!url) {
         throw new Error(`[CONFIG] Missing environment variable: ${keyName}`);
     }
@@ -15,11 +15,12 @@ export function normalizeBaseUrl(url: string | undefined, keyName: string): stri
     // Auto-prefix with https:// if it doesn't start with http
     if (!normalized.startsWith('http')) {
         normalized = `https://${normalized}`;
+        console.warn(`[CONFIG] Warning: Auto-prefixed ${keyName} with https://`);
     }
 
-    // Warn if it's explicitly http in production (except localhost)
-    if (normalized.startsWith('http://') && !normalized.includes('localhost')) {
-        console.warn(`[CONFIG] Warning: ${keyName} is using http:// instead of https:// (${normalized})`);
+    // Strictly forbid http:// in production
+    if (normalized.startsWith('http://') && !normalized.includes('localhost') && !normalized.includes('127.0.0.1')) {
+        throw new Error(`[CONFIG] ❌ CRITICAL: ${keyName} MUST use https:// (got ${normalized})`);
     }
 
     // Remove trailing slashes
@@ -31,10 +32,10 @@ export function normalizeBaseUrl(url: string | undefined, keyName: string): stri
 }
 
 /**
- * Gets the Railway API URL for internal webhook processing and AI endpoints.
+ * Gets the AI API URL for internal webhook processing and endpoints.
  */
 export function getApiUrl(): string {
-    return normalizeBaseUrl(process.env.API_URL, 'API_URL');
+    return requireHttpUrl(process.env.AI_API_BASE_URL, 'AI_API_BASE_URL');
 }
 
 /**
@@ -56,7 +57,8 @@ export function validateEnvironment() {
     console.log('[CONFIG] Validating environment variables...');
 
     const requiredVars = [
-        'API_URL',
+        'AI_API_BASE_URL',
+        'OPENAI_API_KEY',
         'ADMIN_API_KEY',
         'WHATSAPP_ACCESS_TOKEN',
         'WHATSAPP_PHONE_NUMBER_ID',
@@ -84,6 +86,6 @@ export function validateEnvironment() {
 
     // Validate and print effective API URL
     const effectiveApiUrl = getApiUrl();
-    console.log(`[CONFIG] ✅ API_URL effective: ${effectiveApiUrl}`);
+    console.log(`[CONFIG] ✅ AI_API_BASE_URL effective: ${effectiveApiUrl}`);
     console.log(`[CONFIG] ✅ Environment validation passed.`);
 }

apps/whatsapp-worker/src/index.ts

@@ -51,12 +51,12 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
             if (!user?.phone) return;
 
             console.log(`[WORKER] Generating feedback for User ${userId}`);
-            const API_URL = getApiUrl();
+            const AI_API_BASE_URL = getApiUrl();
             const apiKey = getAdminApiKey();
 
             let feedbackMsg = '';
             try {
-                const feedbackRes = await fetch(`${API_URL}/v1/ai/generate-feedback`, {
+                const feedbackRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/generate-feedback`, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
                     body: JSON.stringify({ answers: text, lessonText, exercisePrompt })
@@ -144,9 +144,9 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
             if (track.isPremium) {
                 console.log(`[WORKER] User ${userId} requested Premium Track ${trackId}. Generating Payment Link...`);
                 try {
-                    const API_URL = getApiUrl();
+                    const AI_API_BASE_URL = getApiUrl();
                     const apiKey = getAdminApiKey();
-                    const checkoutRes = await fetch(`${API_URL}/v1/payments/checkout`, {
+                    const checkoutRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/payments/checkout`, {
                         method: 'POST',
                         headers: {
                             'Content-Type': 'application/json',
@@ -210,28 +210,32 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
             let audioUrl = '';
             try {
                 const { buffer } = await downloadMedia(mediaId, accessToken);
+                console.log(`[MEDIA] downloaded file size=${buffer.length} contentType=${mimeType}`);
 
-                const API_URL = getApiUrl();
+                const AI_API_BASE_URL = getApiUrl();
                 const apiKey = getAdminApiKey();
 
                 // Store audio on R2 via the API
                 try {
-                    const storeRes = await fetch(`${API_URL}/v1/ai/store-audio`, {
+                    const storeRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/store-audio`, {
                         method: 'POST',
                         headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
                         body: JSON.stringify({ audioBase64: buffer.toString('base64'), mimeType, phone })
                     });
                     if (storeRes.ok) {
                         const storeData = await storeRes.json() as any;
-                        if (storeData.url) audioUrl = storeData.url;
+                        if (storeData.url) {
+                            audioUrl = storeData.url;
+                            console.log(`[R2] uploaded url=${audioUrl}`);
+                        }
                     }
                 } catch (err) {
                     console.error('[WORKER] store-audio failed to save inbound audio archive (non-blocking)');
                 }
 
                 // Transcribe with Whisper via API
-                console.log(`[WORKER] Calling /v1/ai/transcribe at ${API_URL}`);
-                const transcribeRes = await fetch(`${API_URL}/v1/ai/transcribe`, {
+                console.log(`[STT] transcribe start calling ${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/transcribe`);
+                const transcribeRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/transcribe`, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
                     body: JSON.stringify({ audioBase64: buffer.toString('base64'), filename: `msg.${mimeType.includes('mp4') ? 'mp4' : 'ogg'}` })
@@ -240,14 +244,12 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
                 if (transcribeRes.ok) {
                     const data = await transcribeRes.json() as any;
                     transcribedText = data.text || '';
-                    console.log(`[WORKER] ✅ Transcribed: "${transcribedText.substring(0, 80)}"`);
+                    console.log(`[STT] transcribe result="${transcribedText.substring(0, 80)}"`);
 
                     // Send an immediate confirmation to the user that the audio was understood
                     const user = await prisma.user.findFirst({ where: { phone } });
                     if (user && transcribedText) {
-                        const confirmationText = user.language === 'WOLOF'
-                            ? `✅ Dégg naa la. Lii laa ci jàpp:\n_"${transcribedText}"_`
-                            : `✅ J'ai bien reçu. Voici ce que j'ai compris :\n_"${transcribedText}"_`;
+                        const confirmationText = `J'ai compris :\n"${transcribedText}"`;
                         await sendTextMessage(phone, confirmationText);
                     }
                 } else if (transcribeRes.status === 429) {
@@ -269,7 +271,7 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
 
                 // Process the transcribed text as a normal incoming message via API
                 if (transcribedText) {
-                    await fetch(`${API_URL}/v1/internal/handle-message`, {
+                    await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/internal/handle-message`, {
                         method: 'POST',
                         headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
                         body: JSON.stringify({ phone, text: transcribedText, audioUrl })
@@ -316,28 +318,28 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
                     // Update userContext to explicitly reference the user's sector/activity
                     const userContext = `User ${userId} completed the Business Pitch track. Their business activity/sector is: ${user?.activity || 'Unknown'}. They want to build a business in this sector using the concepts learned in the track.`;
 
-                    const API_URL = getApiUrl();
+                    const AI_API_BASE_URL = getApiUrl();
                     const apiKey = getAdminApiKey();
                     const authHeaders = {
                         'Content-Type': 'application/json',
                         'Authorization': `Bearer ${apiKey}`
                     };
 
-                    // Trigger OnePager (PDF)
-                    const pdfRes = await fetch(`${API_URL}/v1/ai/onepager`, {
+                    console.log(`[WORKER] Calling ${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/onepager...`);
+                    const opRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/onepager`, {
                         method: 'POST',
                         headers: authHeaders,
                         body: JSON.stringify({ userContext })
                     });
-                    const pdfData = await pdfRes.json() as any;
+                    const pdfData = await opRes.json() as any;
 
-                    // Trigger Pitch Deck (PPTX)
-                    const pptxRes = await fetch(`${API_URL}/v1/ai/deck`, {
+                    console.log(`[WORKER] Calling ${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/deck...`);
+                    const deckRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/deck`, {
                         method: 'POST',
                         headers: authHeaders,
                         body: JSON.stringify({ userContext })
                     });
-                    const pptxData = await pptxRes.json() as any;
+                    const pptxData = await deckRes.json() as any;
 
                     console.log(`[AI DOCS READY] 📄 PDF: ${pdfData.url}`);
                     console.log(`[AI DOCS READY] 📊 PPTX: ${pptxData.url}`);

apps/whatsapp-worker/src/pedagogy.ts

@@ -1,6 +1,6 @@
 import { PrismaClient } from '@prisma/client';
 import { sendTextMessage, sendAudioMessage, sendInteractiveButtonMessage, sendInteractiveListMessage } from './whatsapp-cloud';
-import { getApiUrl, getAdminApiKey } from './config';
+import { requireHttpUrl, getAdminApiKey } from './config';
 
 const prisma = new PrismaClient();
 
@@ -28,9 +28,9 @@ export async function sendLessonDay(userId: string, trackId: string, dayNumber:
     if (user.activity && lessonText) {
         try {
             console.log(`[PEDAGOGY] Personalizing lesson for User ${userId}'s activity: ${user.activity}`);
-            const API_URL = getApiUrl();
+            const AI_API_BASE_URL = requireHttpUrl(process.env.AI_API_BASE_URL, 'AI_API_BASE_URL');
             const apiKey = getAdminApiKey();
-            const personalizeRes = await fetch(`${API_URL}/v1/ai/personalize-lesson`, {
+            const personalizeRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/personalize-lesson`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
@@ -56,9 +56,9 @@ export async function sendLessonDay(userId: string, trackId: string, dayNumber:
     if (!finalAudioUrl && lessonText) {
         try {
             console.log(`[PEDAGOGY] Generating TTS Audio for User ${userId}...`);
-            const API_URL = getApiUrl();
+            const AI_API_BASE_URL = requireHttpUrl(process.env.AI_API_BASE_URL, 'AI_API_BASE_URL');
             const apiKey = getAdminApiKey();
-            const ttsRes = await fetch(`${API_URL}/v1/ai/tts`, {
+            const ttsRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/tts`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
                 body: JSON.stringify({ text: lessonText })
@@ -75,8 +75,10 @@ export async function sendLessonDay(userId: string, trackId: string, dayNumber:
 
     if (finalAudioUrl) {
         try {
+            console.log(`[TTS] audioUrl=${finalAudioUrl} sending to WhatsApp...`);
             await sendAudioMessage(user.phone, finalAudioUrl);
-            console.log(`[TTS] Audio generated: ${finalAudioUrl}`);
+            console.log(`[WhatsApp] ✅ Audio message sent to ${user.phone}`);
+
             // Send the text as a separate short message 
             if (lessonText) {
                 await sendTextMessage(user.phone, lessonText);

nixpacks.toml

@@ -0,0 +1,4 @@
+providers = ["node"]
+
+[phases.setup]
+nixPkgs = ["...", "ffmpeg"]