Audio Reports

This workflow processes WhatsApp messages (both text and voice) to generate AI-powered reports for educational programs. It handles user onboarding, role assignment, voice transcription, and creates structured reports that are stored in Google Sheets and sent back to users via WhatsApp.

Purpose

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

Based on the workflow structure, this system appears to serve educational programs (EBA and EXP) by: - Onboarding new users and assigning them appropriate roles (trainers, mentors, or participants) - Processing voice notes and text messages from program stakeholders - Generating AI-powered reports based on user input and their assigned role - Storing reports in Google Sheets for tracking and analysis - Providing immediate feedback to users via WhatsApp

How It Works

1. Message Reception: The workflow receives WhatsApp messages via webhook, supporting both text and audio messages
2. Audio Processing: For voice messages, the system downloads the audio file, converts it to a smaller format if needed (>25MB), and transcribes it using OpenAI Whisper
3. User Validation: Checks if the user exists in the Google Sheets database and has an assigned role
4. User Onboarding: New users go through an AI-powered onboarding process that determines their role in either the EBA or EXP program (roles 0-5: trainers, mentors, or participants)
5. Role Assignment: Users are assigned specific roles and their information is stored in the Users sheet
6. Report Generation: Based on the user's role, the system retrieves the appropriate prompt and uses AI to generate a structured report
7. Data Storage: Generated reports are appended to the Reports sheet with timestamps
8. Response Delivery: The AI response and formatted report are sent back to the user via WhatsApp

Workflow Diagram

graph TD
    A[WhatsApp Webhook] --> B{Is Voice Note?}
    B -->|Yes| C[Download Voice File]
    B -->|No| D[Text Input]
    C --> E{File > 25MB?}
    E -->|Yes| F[CloudConvert Job]
    E -->|No| G[Transcribe Audio]
    F --> H[Wait for Conversion]
    H --> I[Download Converted File]
    I --> G
    G --> J[Extract Text]
    D --> K[User Message]
    J --> K
    K --> L{User Exists?}
    L -->|No| M[Check User in DB]
    M --> N{User in DB?}
    N -->|No| O[Onboarding Agent]
    N -->|Yes| P[Get Current Prompt]
    O --> Q[Assign Role]
    Q --> R[Send Onboarding Response]
    Q --> P
    P --> S[AI Agent]
    S --> T[Append Report]
    T --> U[Send Final Response]

Trigger

WhatsApp Webhook - Activated when messages are received at the /coaching-start endpoint from Twilio WhatsApp integration.

Nodes Used

Node Type	Purpose
Webhook	Receives WhatsApp messages from Twilio
If	Conditional logic for voice detection, file size checks, and user validation
HTTP Request	Downloads voice files and handles CloudConvert API calls
OpenAI	Transcribes audio files using Whisper
Google Sheets	Manages user data, prompts, and report storage
LangChain Agent	Handles user onboarding and report generation with AI
Structured Output Parser	Ensures consistent AI response formatting
OpenAI Chat Model	Powers the AI agents with GPT-4
Memory Buffer	Maintains conversation context per user
Twilio	Sends WhatsApp responses back to users
Set	Data transformation and message formatting
Switch	Routes CloudConvert job status handling
Wait	Handles asynchronous CloudConvert processing

External Services & Credentials Required

Required Services

• Twilio: WhatsApp Business API integration
• OpenAI: GPT-4 model access and Whisper transcription
• Google Sheets: Data storage and user management
• CloudConvert: Audio file compression for large files

Credentials Needed

• twilioApi: Twilio account credentials for WhatsApp messaging
• openAiApi: OpenAI API key for AI models and transcription
• googleApi: Google Service Account for Sheets access
• httpHeaderAuth: CloudConvert API authentication

Environment Variables

No specific environment variables are configured in this workflow. All external service configurations are handled through n8n credential management.

Data Flow

Input

• WhatsApp messages (text or voice) via Twilio webhook
• User identification through WhatsApp phone numbers (WaId)

Processing

• Voice transcription and text extraction
• User role assignment (0-5 based on program and function)
• AI-powered report generation using role-specific prompts
• Conversation memory management per user session

Output

• Structured reports stored in Google Sheets
• WhatsApp responses with AI-generated content and formatted reports
• User database updates with role assignments and timestamps

Error Handling

The workflow includes several error handling mechanisms:

• Audio Conversion Failures: CloudConvert job status monitoring with retry logic
• User Assignment Errors: Graceful handling with continueRegularOutput for role assignment failures
• File Size Management: Automatic compression for audio files exceeding 25MB
• Missing User Data: Fallback to onboarding process for unregistered users
• API Failures: Built-in error handling in HTTP requests and external service calls

Known Limitations

• Audio files must be accessible via public URLs for transcription
• CloudConvert processing introduces latency for large audio files
• Role assignments are limited to predefined options (0-5)
• Conversation memory is session-based and may not persist across long periods
• WhatsApp message size and format limitations apply

Related Workflows

No related workflows are specified in the current context.

Setup Instructions

1. Import Workflow: Import the JSON configuration into your n8n instance

2. Configure Credentials:

   • Set up Twilio credentials for WhatsApp integration
   • Add OpenAI API key for GPT-4 and Whisper access
   • Configure Google Service Account for Sheets access
   • Add CloudConvert API credentials

3. Google Sheets Setup:

   • Create or configure the "E Lab Report" spreadsheet
   • Ensure sheets exist: "Users", "VoiceNotePrompts", "Reports"
   • Set up proper column headers and permissions

4. Webhook Configuration:

   • Configure Twilio webhook to point to your n8n webhook URL
   • Set webhook path to /coaching-start
   • Enable POST method

5. Test the Workflow:

   • Send a test WhatsApp message to verify webhook reception
   • Test both text and voice message processing
   • Verify user onboarding and role assignment flows

6. Monitor and Maintain:

   • Check Google Sheets for proper data storage
   • Monitor CloudConvert usage and quotas
   • Review AI agent responses for quality and accuracy