Skip to content

WhatsApp AI Coaching Assistant

An intelligent WhatsApp chatbot that processes text and voice messages from users, transcribes voice notes, looks up mentor information from a database, and provides AI-powered responses through OpenAI's Assistant API.

Purpose

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

How It Works

  1. Receive Message: A WhatsApp webhook receives incoming messages (text or voice)
  2. Extract Information: The workflow parses the message content, sender details, and checks for voice attachments
  3. Process Voice Notes: If a voice note is detected, it downloads the audio file and transcribes it using OpenAI's Whisper API
  4. Load Mentor Data: Retrieves mentor information from a Google Sheets database
  5. Create AI Thread: Establishes a new conversation thread with OpenAI's Assistant API
  6. Prepare Message: Combines the text message, voice transcription (if any), and detected mentor IDs into a structured prompt
  7. Send to Assistant: Adds the message to the AI thread and runs the assistant
  8. Handle Functions: If the AI needs to look up mentor information, it processes function calls and submits the results
  9. Get Response: Retrieves the AI-generated response from the thread
  10. Format & Send: Formats the response for WhatsApp and sends it back to the user

Workflow Diagram

graph TD
    A[WhatsApp Webhook] --> B[Extract Message Info]
    B --> C[Configuration]
    C --> D{Has Voice Note?}
    D -->|Yes| E[Download Voice File]
    D -->|No| I[Prepare Assistant Message]
    E --> F[Transcribe Voice Note]
    F --> I
    G[Load Mentor Database] --> I
    H[Create Thread] --> I
    I --> J[Add Message to Thread]
    J --> K[Run Assistant]
    K --> L[Wait for Completion]
    L --> M[Check Run Status]
    M --> N{Needs Function Call?}
    M --> O{Is Completed?}
    N -->|Yes| P[Handle Function Calls]
    P --> Q[Submit Function Results]
    Q --> R[Wait After Functions]
    R --> S[Get Assistant Response]
    O -->|Yes| S
    S --> T[Format Response]
    T --> U[Send Response]

Trigger

Webhook: POST endpoint at /coaching-start that receives WhatsApp message data from Twilio's webhook service.

Nodes Used

Node Type Purpose
Webhook Receives incoming WhatsApp messages
Code Extracts message info, prepares assistant data, handles functions, formats responses
Set Stores configuration values (Assistant ID)
If Conditional branching for voice notes and assistant status
HTTP Request Downloads voice files, calls OpenAI APIs, checks run status
Google Sheets Loads mentor database from spreadsheet
Wait Pauses execution for API processing
Twilio Sends WhatsApp responses back to users

External Services & Credentials Required

OpenAI

  • API Key: Required for Whisper transcription and Assistant API
  • Assistant ID: Pre-configured OpenAI assistant (asst_3f6EDOYjPdAeKRTT7q6tKmiy)

Google Sheets

  • Service Account: For accessing mentor database spreadsheet
  • Document ID: 1Vv_gTpvI8RHPPrn0iwzypG3qKRYeLDb1HZFPDzYe5ng

Twilio

  • Account SID & Auth Token: For WhatsApp messaging
  • WhatsApp Number: +14155238886

Environment Variables

The workflow expects these values to be configured: - OpenAI API key in HTTP request headers - Google Service Account credentials - Twilio API credentials

Data Flow

Input

  • WhatsApp message data including:
    • Phone number (From)
    • Message body (Body)
    • Media attachments (NumMedia, MediaUrl0)
    • User profile name (ProfileName)

Output

  • WhatsApp response message sent back to the user
  • Potential for split messages if response exceeds 1500 characters

Internal Data

  • Thread ID for conversation continuity
  • Mentor database records with ID, name, gender, region, position, and lesson history
  • Voice transcriptions when applicable

Error Handling

The workflow includes several error handling mechanisms:

  • Message Processing: Catches errors in message extraction and returns structured error responses
  • Function Handling: Validates function call data and handles missing mentor records
  • Response Formatting: Provides fallback messages when AI responses fail
  • Safe Node Access: Uses defensive programming to handle missing node data

Known Limitations

  • Voice notes must be accessible via public URL for transcription
  • Assistant responses are limited to 1500 characters (longer responses are split)
  • Mentor lookup only works with 6-digit numeric IDs
  • No conversation persistence between webhook calls
  • Hardcoded assistant ID requires manual updates

No related workflows specified in the current context.

Setup Instructions

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

  2. Configure Credentials:

    • Add OpenAI API credentials
    • Set up Google Service Account for Sheets access
    • Configure Twilio API credentials

  3. Update Configuration:

    • Replace <YOUR_OPENAI_API_KEY> in HTTP request headers
    • Verify the Assistant ID in the Configuration node
    • Confirm Google Sheets document ID and sheet name

  4. Set Up Webhook:

    • Activate the workflow to generate webhook URL
    • Configure Twilio WhatsApp webhook to point to the generated URL

  5. Test:

    • Send a test message to your WhatsApp number
    • Verify voice note transcription works
    • Test mentor ID lookup functionality

  6. Monitor:

    • Check execution logs for errors
    • Verify Google Sheets access permissions
    • Monitor OpenAI API usage and rate limits