Skip to content

Audio Reports V3

An intelligent WhatsApp-based reporting system that processes voice messages and text inputs from program participants, automatically transcribes audio content, manages user onboarding with role assignment, and generates structured reports using AI agents tailored to specific user roles within educational programs.

Purpose

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

How It Works

  1. Message Reception: The workflow receives WhatsApp messages via webhook, supporting both text and voice messages
  2. Audio Processing: Voice messages are automatically downloaded and transcribed using OpenAI's speech-to-text service
  3. User Validation: The system checks if the sender exists in the user database using their WhatsApp ID
  4. Smart Onboarding: New users are guided through an AI-powered onboarding process that determines their role (trainer, mentor, or participant) and assigns them to appropriate programs (EBA or EXP)
  5. Role-Based Processing: Existing users are routed to specialized AI agents based on their assigned role, with prompts tailored to their specific responsibilities
  6. Report Generation: AI agents process user input and generate structured reports in markdown format
  7. Data Storage: Reports are automatically saved to Google Sheets with timestamps and user information
  8. Response Delivery: Users receive AI-generated responses via WhatsApp (currently disabled)
  9. Reminder System: 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 or Text?}
    B -->|Voice| C[Download Voice File]
    B -->|Text| D[Text Input]
    C --> E[Transcribe Audio]
    E --> F[Voice Output]
    F --> G[User Message]
    D --> G
    G --> H{User Exists?}
    H -->|No| I[End]
    H -->|Yes| J[Check User in DB]
    J --> K{User Has Role?}
    K -->|No| L[Onboarding Agent]
    K -->|Yes| M[Get Current Prompt]
    L --> N[Assign Role]
    N --> O[Send Onboarding Response]
    N --> M
    M --> P[AI Agent]
    P --> Q[Upsert Report]
    Q --> R[Send AI Response]

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

Trigger

  • Primary: WhatsApp Webhook (POST /afac3d91-a4a3-4dba-b1e8-54d509257815) - Receives incoming WhatsApp messages
  • Secondary: Schedule Trigger - Runs daily at 9 AM and 3 PM to send reminder messages

Nodes Used

Node Type Purpose
Webhook Receives WhatsApp messages from Twilio
HTTP Request Downloads voice message files
OpenAI Transcribe Converts voice messages to text
Google Sheets Reads/writes user data and reports
If Conditions Routes workflow based on message type and user status
Set Variables Formats and prepares data for processing
AI Agent (LangChain) Processes user input with role-specific prompts
Structured Output Parser Ensures AI responses follow defined JSON schema
OpenAI Chat Model Powers the AI agents with GPT-4
Memory Buffer Maintains conversation context per user
Twilio Sends WhatsApp responses (currently disabled)
Code Nodes Custom JavaScript for data processing
Aggregate Combines multiple data items
Schedule Trigger Automated reminder system

External Services & Credentials Required

Required Credentials

  • Google Service Account: For Google Sheets access
    • Service account JSON key file
    • Sheets API enabled
  • OpenAI API: For transcription and chat models
    • API key with access to GPT-4 and Whisper
  • Twilio API: For WhatsApp messaging
    • Account SID
    • Auth Token
    • WhatsApp sandbox or approved number

Google Sheets Structure

  • Document ID: 1-rSu9reEnlEIR80dXusX0GxfmpAUMli-2MXNEVVndgI
  • Users Sheet: Stores UserID, UserName, RoleID
  • VoiceNotePrompts Sheet: Contains role-specific AI prompts
  • Reports Sheet: Stores generated reports with timestamps

Environment Variables

No specific environment variables are configured in this workflow. All configuration is handled through n8n credentials and node parameters.

Data Flow

Input

  • WhatsApp messages (text or voice) via webhook
  • Message metadata including sender WhatsApp ID
  • Voice message URLs for audio files

Processing

  • Audio transcription to text
  • User role identification and assignment
  • AI-powered conversation and report generation
  • Structured data extraction using JSON schemas

Output

  • Structured reports in markdown format
  • User onboarding responses
  • WhatsApp message responses (disabled)
  • Google Sheets updates with user and report data
  • Reminder notifications for inactive users

Error Handling

  • User Lookup: Uses alwaysOutputData to handle cases where users don't exist
  • Role Assignment: Includes onError: continueRegularOutput to prevent workflow failures
  • Best-Fit Assignment: Onboarding agent has fallback logic to assign closest matching roles when user descriptions are unclear
  • Audio Processing: Workflow continues if voice transcription fails by falling back to text processing

Known Limitations

  • WhatsApp responses are currently disabled (Twilio nodes are disabled)
  • Workflow is marked as inactive ("active": false)
  • Limited to predefined role types (0-5) with no custom role creation
  • Reminder system only checks for reports from the previous day
  • No explicit error handling for API rate limits or service outages

No related workflows specified in the current context.

Setup Instructions

  1. Import Workflow

    • Import the JSON into your n8n instance
    • The workflow will be inactive by default

  2. Configure Credentials

    • Set up Google Service Account with Sheets API access
    • Add OpenAI API credentials with GPT-4 access
    • Configure Twilio credentials for WhatsApp messaging

  3. Prepare Google Sheets

    • Create or access the specified Google Sheet
    • Ensure sheets exist: Users, VoiceNotePrompts, Reports
    • Set up proper column headers as defined in the node configurations

  4. Configure Webhook

    • Note the webhook URL from the WhatsApp Webhook node
    • Configure Twilio WhatsApp webhook to point to this URL

  5. Test Setup

    • Send a test message to verify webhook reception
    • Check that audio transcription works with voice messages
    • Verify Google Sheets integration is functioning

  6. Activate Workflow

    • Enable the workflow in n8n
    • Enable Twilio response nodes if WhatsApp replies are needed
    • Monitor the scheduled reminder system

  7. Customize Prompts

    • Update the VoiceNotePrompts sheet with role-specific instructions
    • Adjust onboarding prompts in the Onboarding Agent node
    • Modify response templates as needed for your use case