Audio Reports¶

This workflow provides AI-powered coaching for teachers through WhatsApp voice messages and text. It automatically transcribes voice notes, analyzes teaching practices using role-specific AI prompts, and delivers personalized feedback while maintaining conversation history and logging all interactions to Google Sheets.

Purpose¶

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

How It Works¶

Message Reception: Receives WhatsApp messages via webhook trigger
Message Type Detection: Determines if the message contains audio or is text-only
Audio Processing: For voice messages, downloads the audio file and checks size
Audio Conversion: If audio exceeds 25MB, converts it to smaller format using CloudConvert
Transcription: Uses OpenAI Whisper to convert audio to text
User Lookup: Checks Google Sheets to see if user exists in the system
User Onboarding: For new users, runs onboarding flow to determine their role (trainer, mentor, or participant)
Role Assignment: Saves user information and role to Google Sheets
Prompt Retrieval: Gets role-specific coaching prompts from Google Sheets
AI Analysis: Processes user message using appropriate coaching prompts
Response Generation: Creates personalized feedback and structured reports
Data Logging: Saves the generated report to Google Sheets
Message Delivery: Sends AI response back to user via WhatsApp

Workflow Diagram¶

graph TD
    A[WhatsApp Webhook] --> B[If Voicenote]
    B -->|Audio| C[Download Voice File]
    B -->|Text| D[Text In1]
    C --> E[If > 25mb]
    E -->|Large| F[Create Job]
    E -->|Small| G[Transcribe a recording]
    F --> H[Wait]
    H --> I[GET Job]
    I --> J[Switch]
    J -->|Finished| K[Download Audio File]
    K --> G
    G --> L[Voice Out1]
    L --> M[User Message1]
    D --> M
    M --> N[User Exists?1]
    N --> O[Check User Exists1]
    O --> P[User in DB?1]
    P -->|Exists| Q[Get Current Prompt1]
    P -->|New User| R[Onboarding Agent1]
    R --> S[Assign Role1]
    S --> T[Send Response2]
    S --> Q
    Q --> U[AI Agent]
    U --> V[Append Report1]
    V --> W[Send Response3]

Trigger¶

Type: Webhook
Method: POST
Path: /coaching-start
Source: WhatsApp messages via Twilio

Nodes Used¶

Node Type	Purpose
Webhook	Receives WhatsApp messages from Twilio
If	Conditional logic for message type and file size checks
HTTP Request	Downloads audio files and handles CloudConvert API
Wait	Pauses execution during audio conversion
Switch	Routes based on conversion job status
OpenAI	Transcribes audio using Whisper API
Set	Transforms and prepares data between steps
Google Sheets	Manages user data, prompts, and report storage
LangChain Agent	Handles onboarding conversations and coaching analysis
OpenAI Chat Model	Powers the AI agents with GPT-4
Structured Output Parser	Ensures consistent AI response format
Memory Buffer	Maintains conversation context
Twilio	Sends responses back via WhatsApp

External Services & Credentials Required¶

Required Services¶

Twilio: WhatsApp Business API integration
OpenAI: GPT-4 and Whisper API access
Google Sheets: Data storage and prompt 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 token for file conversion

Environment Variables¶

No specific environment variables are configured in this workflow. All external service connections use stored credentials.

Data Flow¶

Input¶

WhatsApp messages (text or audio) via Twilio webhook
Message metadata including sender ID, message type, and media URLs

Processing¶

Audio transcription to text
User role identification and onboarding
Role-specific prompt retrieval
AI-powered coaching analysis

Output¶

Personalized coaching feedback sent via WhatsApp
Structured reports logged to Google Sheets
User data and conversation history maintained

Error Handling¶

Audio Conversion Failures: Switch node handles different CloudConvert job statuses
User Assignment Errors: Assign Role node continues on error to prevent workflow stoppage
Large File Handling: Automatic compression for audio files over 25MB
Always Output Data: User lookup nodes ensure workflow continues even with missing data

Known Limitations¶

Audio files must be accessible via public URL for processing
CloudConvert processing adds latency for large audio files
Conversation memory is session-based and may not persist long-term
Role assignment is limited to predefined categories (0-5)

The workflow documentation mentions that "Audio Reports V3" is available with enhanced features: - Scheduled reminders - Improved coaching logic

Consider using V3 for new implementations.

Setup Instructions¶

Import Workflow: Import the JSON into your n8n instance
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 token for file conversion
Prepare Google Sheets:
- Create spreadsheet with ID: 1Vv_gTpvI8RHPPrn0iwzypG3qKRYeLDb1HZFPDzYe5ng
- Set up sheets: "Users", "VoiceNotePrompts", "Reports"
- Configure appropriate column headers for user data and reports
Configure Webhook:
- Set up Twilio WhatsApp webhook to point to your n8n webhook URL
- Ensure webhook path matches: /coaching-start
Test Setup:
- Send a test WhatsApp message to verify webhook reception
- Test both text and audio message processing
- Verify user onboarding flow for new users
- Confirm reports are being logged to Google Sheets
Customize Prompts:
- Update the VoiceNotePrompts sheet with role-specific coaching prompts
- Adjust onboarding agent prompts as needed for your use case