How huntingphi/voice-to-note works
Project Type and Purpose
• Type: A serverless/flask‐based WhatsApp bot that transcribes audio to text.
• Purpose: Receive voice notes via Twilio WhatsApp, fetch the audio from S3, run it through Google Cloud Speech-to-Text, and reply with the transcription.
Main Components
• User Device: WhatsApp client that sends/receives voice notes.
• Twilio WhatsApp Sandbox: Entry point for incoming messages and voice notes; handles webhooks and callbacks.
• S3 Bucket: Storage location for voice note media.
• API Endpoint (Flask on AWS Lambda):
• lambda_function.py handles incoming HTTP POSTs from Twilio.
• fetch_vn.py downloads the media file from S3 via Twilio’s provided URL.
• recognize_speech.py calls Google Cloud Speech-to-Text API and returns the transcript.
• Google Cloud Speech-to-Text API: External service for speech recognition.
• Twilio Messaging API: Sends the text response back to the user.
Relationships and Data Flow
1. User records voice note in WhatsApp → Twilio Sandbox receives it.
2. Twilio issues a webhook POST to /bot-receiver on your Flask/Lambda endpoint.
3. lambda_function.py parses the request and extracts the media URL.
4. fetch_vn.py downloads the audio file from S3 (using Twilio’s signed URL).
5. recognize_speech.py sends audio to Google Cloud STT → receives transcript.
6. lambda_function.py posts the transcript back to the user via Twilio’s API (HTTP POST).
7. (Optional) Twilio posts status updates to /bot-status for delivery callbacks.
Architectural Patterns and Design Principles
• Serverless / Function-as-a-Service: The Flask app runs in AWS Lambda.
• Webhook-Driven Flow: Twilio callbacks trigger your service.
• Single Responsibility Modules: Separate scripts for fetching media and speech recognition.
• Externalized Configuration: Environment variables for Google credentials and Twilio tokens.
• Stateless Request Handling: Each webhook invocation is independent.
Final Checklist
• Clear, descriptive component labels.
• Callout for environment/configuration (AWS Lambda env vars).
• A concise note on “No persistent state” to indicate stateless design.