Audio Reports V3¶

A voice-based coaching system that enables trainers and mentors in youth empowerment programs to send voice notes via WhatsApp and receive AI-powered feedback and structured reports. The system supports both EBA (entrepreneurship training for out-of-school youth) and EXP (21^st century skills development for in-school students) programs, with automated user onboarding, role assignment, and daily reminder functionality.

Purpose¶

No business context provided yet — add a context.md to enrich this documentation.

This workflow serves as an intelligent coaching assistant for educational programs, enabling: - Trainers and Mentors: Send voice notes about their teaching practice and receive personalized coaching feedback - Program Participants: Share reflections and receive structured guidance - Program Administrators: Track engagement through automated reporting and reminders

The system addresses the need for scalable, accessible coaching support in youth development programs where participants may prefer voice communication over text and need regular feedback to improve their practice.

How It Works¶

Message Reception: Users send voice notes or text messages via WhatsApp to a dedicated number
Audio Processing: If a voice note is received, the system downloads the audio file and transcribes it using OpenAI Whisper
User Verification: The system checks if the user exists in the Google Sheets database
Role Assignment: New users go through an AI-powered onboarding process that determines their role (trainer, mentor, or participant) and assigns them to the appropriate program (EBA or EXP)
Prompt Retrieval: Based on the user's role, the system fetches the appropriate coaching prompts from Google Sheets
AI Analysis: An AI agent analyzes the user's message using role-specific prompts and generates structured feedback
Report Generation: The system creates a formatted report with coaching insights and recommendations
Response Delivery: The AI response and report are sent back to the user via WhatsApp
Data Logging: All reports are stored in Google Sheets for tracking and analysis
Automated Reminders: A scheduled trigger runs twice daily to identify users who haven't submitted reports and sends reminder messages

Workflow Diagram¶

graph TD
    A[WhatsApp Webhook] --> B{Voice Note?}
    B -->|Yes| C[Download Voice File]
    B -->|No| D[Text Input]
    C --> E[Transcribe Audio]
    E --> F[Voice Output]
    D --> G[User Message]
    F --> G
    G --> H{User Exists?}
    H -->|No| I[Check User in DB]
    I --> J{User in DB?}
    J -->|No| K[Onboarding Agent]
    K --> L[Assign Role]
    L --> M[Get Current Prompt]
    J -->|Yes| M
    M --> N[AI Agent]
    N --> O[Upsert Report]
    O --> P[Send Response]

    Q[Schedule Trigger] --> R[Get Reports Data]
    R --> S[Process Report Dates]
    S --> T[Find Missing Reports]
    T --> U[Send Reminders]

Triggers¶

WhatsApp Webhook: Responds to incoming messages at /webhook/afac3d91-a4a3-4dba-b1e8-54d509257815
Schedule Trigger: Runs daily at 9:00 AM and 3:00 PM to send reminder messages

Nodes Used¶

Node Type	Purpose
Webhook	Receives WhatsApp messages via Twilio
HTTP Request	Downloads voice files from Twilio media URLs
OpenAI (Transcribe)	Converts voice notes to text using Whisper
Google Sheets	Manages user data, prompts, and report storage
LangChain AI Agent	Processes messages and generates coaching feedback
Structured Output Parser	Ensures AI responses follow required JSON format
OpenAI Chat Model	Powers the AI agents (GPT-4 and GPT-4 Mini)
Memory Buffer	Maintains conversation context for each user
If (Conditional)	Routes logic based on message type and user status
Set	Transforms and prepares data between nodes
Twilio	Sends WhatsApp responses back to users
Schedule Trigger	Initiates daily reminder workflows
Code	Processes report data to identify inactive users
Aggregate	Combines multiple data items for processing

External Services & Credentials Required¶

Required Services¶

Twilio: WhatsApp Business API integration
OpenAI: GPT models and Whisper transcription
Google Sheets: User database and report storage

Credentials Needed¶

openAiApi (Waringa): OpenAI API key for GPT models and Whisper
googleApi (Google Service Account Waringa): Service account for Google Sheets access
Twilio credentials: Account SID and Auth Token for WhatsApp messaging

Environment Variables¶

No specific environment variables are configured in this workflow. All sensitive data is managed through n8n's credential system.

Data Flow¶

Input¶

WhatsApp Messages: Voice notes or text messages from users
User Data: Stored in Google Sheets (UserID, UserName, RoleID)
Prompts: Role-specific coaching prompts from Google Sheets

Output¶

AI Responses: Personalized coaching feedback sent via WhatsApp
Structured Reports: Markdown-formatted coaching reports
Database Updates: User registrations and report logs in Google Sheets
Reminder Messages: Automated prompts for inactive users

Data Structure¶

{
  "ai_response": "Coaching feedback text",
  "report_markdown": "## Structured coaching report",
  "user_name": "Full Name",
  "role_id": 0-5,
  "program": "EBA or EXP"
}

Error Handling¶

User Lookup: The "Check User Exists" node has alwaysOutputData enabled to handle cases where users aren't found
Role Assignment: The "Assign Role" node continues on error to prevent workflow failures during user registration
Conditional Logic: Multiple IF nodes validate user existence and message types before processing
Memory Management: Session-based memory ensures conversation context is maintained per user

Known Limitations¶

Voice note transcription quality depends on audio clarity and OpenAI Whisper capabilities
The system requires manual setup of Google Sheets with specific column structures
Twilio WhatsApp integration has rate limits and requires approved message templates
AI responses are limited by the configured OpenAI model capabilities and prompt engineering
Reminder system only checks for reports from the previous day, not longer periods of inactivity

No related workflows are mentioned in the current documentation.

Setup Instructions¶

1. Import Workflow¶

Import the workflow JSON into your n8n instance
Ensure all required nodes and integrations are available

2. Configure Credentials¶

Set up OpenAI API credentials with access to GPT-4 and Whisper
Create Google Service Account with access to Google Sheets API
Configure Twilio credentials for WhatsApp Business API

3. Prepare Google Sheets¶

Create a Google Sheet with the following structure:

Users Sheet: - Columns: UserID, UserName, RoleID

VoiceNotePrompts Sheet: - Columns: RoleID, Prompt (coaching prompts for each role 0-5)

Reports Sheet: - Columns: UserID, Report_date, Report

4. Configure Webhook¶

Set up Twilio WhatsApp webhook to point to your n8n webhook URL
Update the webhook path in the WhatsApp Webhook node if needed

5. Test the System¶

Send a test voice note to your WhatsApp number
Verify transcription, user registration, and AI response
Check that data is properly logged in Google Sheets
Test the reminder system by running the schedule trigger manually

6. Activate Workflow¶

Enable the workflow to start processing real messages
Monitor the schedule trigger for daily reminder functionality