Skip to content

AudioReports3

A WhatsApp-based AI coaching assistant that processes text and voice messages, provides intelligent responses using OpenAI's Assistant API, and can look up mentor information from Google Sheets. The workflow handles both text-only conversations and voice note transcription, with smart mentor ID detection and database integration.

Purpose

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

This workflow serves as an intelligent WhatsApp chatbot that can: - Process incoming text and voice messages from WhatsApp users - Transcribe voice notes using OpenAI's speech-to-text capabilities - Detect mentor IDs (6-digit numbers) in messages and fetch relevant data - Provide contextual responses using an OpenAI Assistant - Handle function calls for mentor lookups from Google Sheets data

How It Works

  1. Message Reception: The workflow receives WhatsApp messages via Twilio webhook
  2. Message Processing: Extracts phone number, message content, and checks for voice attachments
  3. Voice Transcription: If a voice note is present, it gets transcribed using OpenAI's Whisper
  4. Mentor Detection: Scans message text for 6-digit mentor IDs
  5. Data Loading: If a mentor ID is found, loads relevant mentor data from Google Sheets
  6. Thread Creation: Creates or uses existing OpenAI conversation thread
  7. Message Preparation: Combines text, transcription, and mentor context into a comprehensive message
  8. AI Processing: Sends message to OpenAI Assistant and waits for processing
  9. Function Handling: If the assistant needs mentor data, provides it via function calls
  10. Response Delivery: Extracts the assistant's response and sends it back via WhatsApp

Workflow Diagram

graph TD
    A[WhatsApp Webhook] --> B[Extract Message Info]
    B --> C[Set Configuration]
    C --> D{Has Voice Note?}
    C --> E{Has Mentor ID?}
    C --> F[Create Conversation Thread]

    D -->|Yes| G[Prepare Voice Note]
    D -->|No| H[Prepare Message for Assistant]
    G --> I[Transcribe Voice Note]
    I --> J[Prepare Message for Assistant1]

    E -->|Yes| K[Load Specific Mentor Data]
    E -->|No| H
    K --> L[Filter Mentor Data]
    L --> H

    F --> H
    H --> M[Add Message to Thread]
    M --> N[Run Assistant]
    N --> O[Wait for Processing]
    O --> P[Check Run Status]

    P --> Q{Is Completed?}
    P --> R{Needs Function Call?}

    Q -->|Yes| S[Get Assistant Response]
    Q -->|No| T[Send Processing Message]

    R -->|Yes| U[Handle Function Calls]
    U --> V[Submit Function Results]
    V --> W[Wait After Functions]
    W --> S

    S --> X[Extract Assistant Response]
    X --> Y[Send WhatsApp Response]

    J --> Z[Add Message to Thread1]
    Z --> AA[Run Assistant1]
    AA --> BB[Wait for Processing1]
    BB --> CC[Check Run Status1]
    CC --> DD{Is Completed?1}
    CC --> EE{Needs Function Call?1}
    DD -->|Yes| FF[Get Assistant Response1]
    DD -->|No| GG[Send Processing Message1]
    EE -->|Yes| HH[Handle Function Calls1]
    HH --> II[Submit Function Results1]
    II --> JJ[Wait After Functions1]
    JJ --> FF
    FF --> KK[Extract Assistant Response1]
    KK --> LL[Send WhatsApp Response1]

Trigger

Webhook Trigger: The workflow is triggered by HTTP POST requests to the /coaching-start endpoint from Twilio's WhatsApp webhook system when users send messages.

Nodes Used

Node Type Purpose
Webhook Receives incoming WhatsApp messages from Twilio
Code (JavaScript) Processes message data, handles mentor filtering, and formats responses
HTTP Request Makes API calls to OpenAI Assistant API and Google Sheets API
OpenAI Transcribes voice notes using Whisper
Twilio Sends WhatsApp responses back to users
Set Configures workflow variables like Assistant ID
If Conditional logic for voice notes, mentor IDs, and processing status
Wait Adds delays for API processing and function execution

External Services & Credentials Required

Required Credentials:

  • OpenAI API: For Assistant API and voice transcription
  • Twilio API: For WhatsApp messaging
  • Google Sheets API: For mentor data access (Service Account or OAuth2)

External Services:

  • Twilio WhatsApp Business API: Message routing and delivery
  • OpenAI Assistant API: AI conversation handling
  • OpenAI Whisper API: Voice note transcription
  • Google Sheets API: Mentor database access

Environment Variables

The workflow uses these configuration values (set in the "Set Configuration" node): - assistantId: OpenAI Assistant ID (currently: asst_3f6EDOYjPdAeKRTT7q6tKmiy) - googleSheetId: Google Sheets document ID for mentor data

Data Flow

Input:

  • WhatsApp message webhook payload from Twilio
  • Voice notes (audio files) when present
  • Text messages with potential mentor IDs

Processing:

  • Message text and metadata extraction
  • Voice-to-text transcription
  • Mentor ID detection and database lookup
  • AI conversation context building
  • OpenAI Assistant interaction with function calling

Output:

  • WhatsApp text responses sent back to users
  • Contextual information about mentors when requested
  • Error messages for processing issues

Error Handling

The workflow includes several error handling mechanisms:

  1. Message Processing Errors: JavaScript nodes wrap operations in try-catch blocks
  2. API Failures: Fallback responses when OpenAI or Google Sheets APIs fail
  3. Processing Timeouts: "Still processing" messages sent when AI takes too long
  4. Missing Data: Graceful handling when mentor IDs aren't found in database
  5. Voice Transcription Failures: Continues with text-only processing if transcription fails

Known Limitations

  • Voice notes must be in supported audio formats (primarily audio/ogg)
  • Mentor IDs must be exactly 6 digits to be detected
  • Response length is limited to 1500 characters for WhatsApp compatibility
  • Google Sheets data is loaded fresh for each mentor lookup (no caching)
  • Workflow contains duplicate node chains that could be consolidated

No related workflows specified in the current context.

Setup Instructions

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

  2. Configure Credentials:

    • Set up OpenAI API credentials with access to Assistant API and Whisper
    • Configure Twilio credentials with WhatsApp Business API access
    • Set up Google Sheets API access (Service Account recommended)

  3. Update Configuration:

    • Modify the Assistant ID in "Set Configuration" node
    • Update Google Sheets ID for your mentor database
    • Ensure your Google Sheet has columns including mentor_id, mentor_name, position, region, etc.

  4. Webhook Setup:

    • Copy the webhook URL from the "WhatsApp Webhook1" node
    • Configure this URL in your Twilio WhatsApp webhook settings
    • Set webhook method to POST

  5. Test the Workflow:

    • Send a test message to your Twilio WhatsApp number
    • Verify voice note transcription works
    • Test mentor ID detection with a 6-digit number
    • Confirm responses are delivered back to WhatsApp

  6. Activate: Enable the workflow to start processing live WhatsApp messages

Note: The workflow contains duplicate processing chains that should be consolidated for production use. Consider removing the redundant nodes (those ending with "1") after confirming the primary chain works correctly.