feat: implement STT inbound audio, TTS fallback, and Interactive Lists

apps/api/src/routes/ai.ts

@@ -64,16 +64,22 @@ export async function aiRoutes(fastify: FastifyInstance) {
     });
 
     // 4. Generate TTS Audio for a lesson
-    fastify.post('/tts', async (request) => {
+    fastify.post('/tts', async (request, reply) => {
         const bodySchema = z.object({ text: z.string() });
         const { text } = bodySchema.parse(request.body);
 
         console.log(`Generating TTS audio...`);
 
-        const audioBuffer = await aiService.generateSpeech(text);
-        const downloadUrl = await uploadFile(audioBuffer, `lesson-audio-${Date.now()}.mp3`, 'audio/mpeg');
-
-        return { success: true, url: downloadUrl };
+        try {
+            const audioBuffer = await aiService.generateSpeech(text);
+            const downloadUrl = await uploadFile(audioBuffer, `lesson-audio-${Date.now()}.mp3`, 'audio/mpeg');
+            return { success: true, url: downloadUrl };
+        } catch (err: any) {
+            if (err?.name === 'QuotaExceededError') {
+                return reply.code(429).send({ error: 'quota_exceeded' });
+            }
+            throw err;
+        }
     });
 
     // 5. Transcribe audio (called by Railway worker after downloading media from Meta)

apps/api/src/routes/internal.ts

@@ -7,7 +7,7 @@ import { WhatsAppService } from '../services/whatsapp';
  */
 export async function internalRoutes(fastify: FastifyInstance) {
     fastify.post<{
-        Body: { phone: string; text: string }
+        Body: { phone: string; text: string; audioUrl?: string }
     }>('/v1/internal/handle-message', {
         config: { requireAuth: true } as any,
         schema: {
@@ -16,18 +16,19 @@ export async function internalRoutes(fastify: FastifyInstance) {
                 required: ['phone', 'text'],
                 properties: {
                     phone: { type: 'string' },
-                    text: { type: 'string' }
+                    text: { type: 'string' },
+                    audioUrl: { type: 'string' }
                 }
             }
         }
     }, async (request, reply) => {
-        const { phone, text } = request.body;
-        if (!phone || !text) {
+        const { phone, text, audioUrl } = request.body;
+        if (!phone || text === undefined) {
             return reply.code(400).send({ error: 'phone and text are required' });
         }
 
         // Fire and return — processing is async
-        WhatsAppService.handleIncomingMessage(phone, text).catch((err: Error) => {
+        WhatsAppService.handleIncomingMessage(phone, text, audioUrl).catch((err: Error) => {
             request.log.error(`[INTERNAL] handleIncomingMessage error: ${err.message}`);
         });
 

apps/api/src/services/ai/openai-provider.ts

@@ -79,13 +79,20 @@ export class OpenAIProvider implements LLMProvider {
     async generateSpeech(text: string): Promise<Buffer> {
         console.log('[OPENAI] Generating speech TTS...');
 
-        const mp3 = await this.openai.audio.speech.create({
-            model: 'tts-1',
-            voice: 'alloy',
-            input: text,
-        });
-
-        return Buffer.from(await mp3.arrayBuffer());
+        try {
+            const mp3 = await this.openai.audio.speech.create({
+                model: 'tts-1',
+                voice: 'alloy',
+                input: text,
+            });
+            return Buffer.from(await mp3.arrayBuffer());
+        } catch (err: any) {
+            if (err?.status === 429 || err?.code === 'insufficient_quota') {
+                console.warn('[OPENAI] 429 on generateSpeech');
+                throw new QuotaExceededError();
+            }
+            throw err;
+        }
     }
 }
 

apps/api/src/services/whatsapp.ts

@@ -3,9 +3,9 @@ import { scheduleMessage, enrollUser, whatsappQueue, scheduleTrackDay, scheduleI
 import { QuotaExceededError } from './ai/openai-provider';
 
 export class WhatsAppService {
-    static async handleIncomingMessage(phone: string, text: string) {
+    static async handleIncomingMessage(phone: string, text: string, audioUrl?: string) {
         const normalizedText = text.trim().toUpperCase();
-        console.log(`Received message from ${phone}: ${normalizedText}`);
+        console.log(`Received message from ${phone}: ${normalizedText} (Audio: ${audioUrl || 'N/A'})`);
 
         // 1. Find or Create User
         let user = await prisma.user.findUnique({ where: { phone } });
@@ -27,6 +27,20 @@ export class WhatsAppService {
             }
         }
 
+        // 1.2 Log the incoming message in the DB
+        try {
+            await prisma.message.create({
+                data: {
+                    content: text,
+                    mediaUrl: audioUrl,
+                    direction: 'INBOUND',
+                    userId: user.id
+                }
+            });
+        } catch (err: any) {
+            console.error('[WhatsAppService] Failed to log incoming message:', err.message);
+        }
+
         // 1.5. Testing / Cheat Codes (Only for registered users)
         if (normalizedText === 'INSCRIPTION') {
             await prisma.enrollment.deleteMany({ where: { userId: user.id } });
@@ -64,8 +78,8 @@ export class WhatsAppService {
         }
 
         // ─── Interactive LIST action IDs ──────────────────────────────────────
-        // Format: DAY{N}_EXERCISE | DAY{N}_REPLAY | DAY{N}_CONTINUE
-        const dayActionMatch = normalizedText.match(/^DAY(\d+)_(EXERCISE|REPLAY|CONTINUE)$/);
+        // Format: DAY{N}_EXERCISE | DAY{N}_REPLAY | DAY{N}_CONTINUE | DAY{N}_PROMPT
+        const dayActionMatch = normalizedText.match(/^DAY(\d+)_(EXERCISE|REPLAY|CONTINUE|PROMPT)$/);
         if (dayActionMatch) {
             const action = dayActionMatch[2];
 
@@ -87,10 +101,25 @@ export class WhatsAppService {
                 return;
             } else if (action === 'EXERCISE') {
                 await scheduleMessage(user.id, user.language === 'WOLOF'
-                    ? "🎙️ Yónnee sa tontu (audio walla texte) :"
+                    ? "🎙️ Yónnee sa tontu (audio walla bind) :"
                     : "🎙️ Envoie ta réponse (audio ou texte) :"
                 );
                 return;
+            } else if (action === 'PROMPT') {
+                const enrollment = await prisma.enrollment.findFirst({
+                    where: { userId: user.id, status: 'ACTIVE' }
+                });
+                if (enrollment) {
+                    const trackDay = await prisma.trackDay.findFirst({
+                        where: { trackId: enrollment.trackId, dayNumber: enrollment.currentDay }
+                    });
+                    if (trackDay?.exercisePrompt) {
+                        await scheduleMessage(user.id, trackDay.exercisePrompt);
+                    } else {
+                        await scheduleMessage(user.id, user.language === 'WOLOF' ? "Amul lëjj" : "Pas d'exercice pour ce jour");
+                    }
+                }
+                return;
             }
             // CONTINUE → fall through to SUITE logic below
         }

apps/whatsapp-worker/src/index.ts

@@ -120,19 +120,26 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
             console.log(`[WORKER] Downloading media ${mediaId} for ${phone}...`);
 
             let transcribedText = '';
+            let audioUrl = '';
             try {
                 const { buffer } = await downloadMedia(mediaId, accessToken);
 
-                // Best-effort: store audio on R2 via the API (non-blocking, silent if fails)
-                // No direct require — that path doesn't exist in the worker Docker image
+                // Store audio on R2 via the API
                 const API_URL_STORE = process.env.API_URL || 'http://localhost:3001';
                 const apiKeyStore = process.env.ADMIN_API_KEY || '';
-                fetch(`${API_URL_STORE}/v1/ai/store-audio`, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKeyStore}` },
-                    body: JSON.stringify({ audioBase64: buffer.toString('base64'), mimeType, phone })
-                }).catch(() => { /* silent — audio archiving is optional */ });
-
+                try {
+                    const storeRes = await fetch(`${API_URL_STORE}/v1/ai/store-audio`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKeyStore}` },
+                        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;
+                    }
+                } catch (err) {
+                    console.error('[WORKER] store-audio failed to save inbound audio archive (non-blocking)');
+                }
 
                 // Transcribe with Whisper via API
                 const API_URL = process.env.API_URL || 'http://localhost:3001';
@@ -148,17 +155,15 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
                     transcribedText = data.text || '';
                     console.log(`[WORKER] ✅ Transcribed: "${transcribedText.substring(0, 80)}"`);
                 } else if (transcribeRes.status === 429) {
-                    // OpenAI quota exceeded — send fallback and requeue
+                    // OpenAI quota exceeded — send fallback and do NOT requeue (requested by user to not block)
                     const user = await prisma.user.findFirst({ where: { phone } });
                     if (user) {
                         await sendTextMessage(phone, user.language === 'WOLOF'
-                            ? "Bañ ma dégg sa kàddu léegi. Yónnee ci 2 minute."
-                            : "Je n'arrive pas à analyser l'audio maintenant. Réessaie dans 2 minutes ou envoie ta réponse en texte."
+                            ? "Bañ ma dégg sa kàddu léegi. Yónnee sa tontu ci bind (texte)."
+                            : "Je n'arrive pas à analyser l'audio maintenant. Envoie ta réponse en texte (1 phrase)."
                         );
                     }
-                    // Requeue with 2-minute delay
-                    const requeueQ = new Queue('whatsapp-queue', { connection: connection as any });
-                    await requeueQ.add('download-media', job.data, { delay: 120_000, priority: 1 });
+                    // Stop processing. The user will still be PENDING in DB, waiting for text reply.
                     return;
                 }
             } catch (err: any) {
@@ -174,7 +179,7 @@ const worker = new Worker('whatsapp-queue', async (job: Job) => {
                 await fetch(`${API_URL}/v1/internal/handle-message`, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
-                    body: JSON.stringify({ phone, text: transcribedText })
+                    body: JSON.stringify({ phone, text: transcribedText, audioUrl })
                 }).catch(e => console.error('[WORKER] handle-message call failed:', e.message));
             }
         }

apps/whatsapp-worker/src/pedagogy.ts

@@ -101,16 +101,21 @@ export async function sendLessonDay(userId: string, trackId: string, dayNumber:
         [{
             title: isWolof ? "Jëfandikoo" : "Actions",
             rows: [
-                {
-                    id: `DAY${dayNumber}_EXERCISE`,
-                    title: isWolof ? "🎙️ Yónni tontu" : "🎙️ Répondre",
-                    description: isWolof ? "Yónnee sa tontu ji" : "Envoyer ta réponse à l'exercice"
-                },
                 {
                     id: `DAY${dayNumber}_REPLAY`,
-                    title: isWolof ? "🔁 Dégg ci kanam" : "🔁 Réécouter",
+                    title: isWolof ? "🎧 Dégg ci kanam" : "🎧 Réécouter",
                     description: isWolof ? "Waxtu bi ci kaw" : "Réécouter la leçon"
                 },
+                {
+                    id: `DAY${dayNumber}_PROMPT`,
+                    title: isWolof ? "📝 Lëjj bi" : "📝 Faire l'exercice",
+                    description: isWolof ? "Jàngaat laaj bi" : "Relire la question"
+                },
+                {
+                    id: `DAY${dayNumber}_EXERCISE`,
+                    title: isWolof ? "🎙️ Yónni tontu" : "🎙️ Répondre",
+                    description: isWolof ? "Yónnee sa tontu ji" : "Envoyer ta réponse"
+                },
                 {
                     id: `DAY${dayNumber}_CONTINUE`,
                     title: isWolof ? "⏭️ Ci kanam" : "⏭️ Passer",

packages/database/prisma/schema.prisma

@@ -113,6 +113,8 @@ model Message {
   userId    String
   direction Direction // INBOUND, OUTBOUND
   channel   String   @default("WHATSAPP")
+  content   String?
+  mediaUrl  String?
   payload   Json?    // Raw payload from provider
   createdAt DateTime @default(now())