WhatsApp AI Coaching Assistant¶

An intelligent WhatsApp bot that processes text and voice messages from users, leverages OpenAI's Assistant API to provide coaching responses, and can look up mentor information from a Google Sheets database. The workflow handles voice note transcription, mentor database queries, and delivers contextual responses back to users via WhatsApp.

Purpose¶

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

This workflow appears to be designed for a coaching or mentoring program where users can interact with an AI assistant via WhatsApp to get guidance, ask questions, and look up information about mentors. The system supports both text and voice messages, making it accessible for users who prefer different communication methods.

How It Works¶

Message Reception: A WhatsApp webhook receives incoming messages from users
Message Processing: The system extracts phone number, message content, profile name, and checks for voice notes or potential mentor IDs
Voice Handling: If a voice note is detected, it downloads the audio file and transcribes it using OpenAI's Whisper API
Data Loading: The workflow loads mentor information from a Google Sheets database
Thread Creation: Creates a new OpenAI conversation thread for the interaction
Message Preparation: Combines text, voice transcription, and detected mentor IDs into a structured message
AI Processing: Sends the message to OpenAI's Assistant API and runs the assistant
Function Handling: If the assistant needs to look up mentor information, it processes function calls and submits results back
Response Formatting: Extracts and formats the assistant's response, handling long messages by splitting them
Response Delivery: Sends the formatted response back to the user via WhatsApp

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 Trigger: The workflow is triggered by incoming WhatsApp messages via a webhook endpoint at /coaching-start. The webhook expects POST requests from Twilio's WhatsApp API containing message data including sender information, message content, and media attachments.

Nodes Used¶

Node Type	Node Name	Purpose
Webhook	WhatsApp Webhook1	Receives incoming WhatsApp messages
Code	Extract Message Info	Parses webhook data and extracts message details
Set	Configuration	Sets the OpenAI Assistant ID
If	Has Voice Note?	Checks if message contains voice note
HTTP Request	Download Voice File	Downloads voice note media file
HTTP Request	Transcribe Voice Note	Transcribes audio using OpenAI Whisper
Google Sheets	Load Mentor Database	Loads mentor data from spreadsheet
HTTP Request	Create Thread	Creates new OpenAI conversation thread
Code	Prepare Assistant Message	Combines all message data for AI processing
HTTP Request	Add Message to Thread	Adds user message to OpenAI thread
HTTP Request	Run Assistant	Executes the OpenAI assistant
Wait	Wait for Completion	Pauses for assistant processing
HTTP Request	Check Run Status	Checks if assistant run is complete
If	Needs Function Call?	Determines if function calling is required
If	Is Completed?	Checks if assistant run finished
Code	Handle Function Calls	Processes mentor lookup function calls
HTTP Request	Submit Function Results	Returns function results to OpenAI
Wait	Wait After Functions	Pauses after function submission
HTTP Request	Get Assistant Response	Retrieves assistant's response
Code	Format Response	Formats and splits long responses
Twilio	Send Response	Sends formatted response via WhatsApp

External Services & Credentials Required¶

OpenAI API¶

Purpose: Assistant API for AI responses, Whisper API for voice transcription
Authentication: API Key (Bearer token)
Endpoints Used:
- /v1/threads (thread management)
- /v1/threads/{thread_id}/messages (message handling)
- /v1/threads/{thread_id}/runs (assistant execution)
- /v1/audio/transcriptions (voice transcription)

Google Sheets API¶

Purpose: Mentor database storage and retrieval
Authentication: Service Account credentials
Credential Name: "Google Service Account account"
Document ID: 1Vv_gTpvI8RHPPrn0iwzypG3qKRYeLDb1HZFPDzYe5ng

Twilio WhatsApp API¶

Purpose: Sending WhatsApp messages
Authentication: Twilio API credentials
Credential Name: "Twilio account"
Phone Number: +14155238886 (Twilio sandbox number)

Environment Variables¶

The following API keys and credentials need to be configured:

OpenAI API Key: Replace <YOUR_OPENAI_API_KEY> in HTTP request headers
Assistant ID: Currently set to asst_3f6EDOYjPdAeKRTT7q6tKmiy in Configuration node
Google Service Account: JSON credentials for Google Sheets access
Twilio Credentials: Account SID and Auth Token for WhatsApp messaging

Data Flow¶

Input¶

WhatsApp Message Data: Phone number, message body, profile name, media attachments
Voice Notes: Audio files that get transcribed to text
Mentor Database: Spreadsheet with mentor information including ID, name, gender, region, position, and lesson history

Processing¶

Message Parsing: Extracts user details and detects mentor ID patterns
Voice Transcription: Converts audio to text using Whisper API
AI Conversation: Creates threaded conversation with OpenAI Assistant
Function Calling: Looks up mentor information when requested
Response Formatting: Handles long responses by splitting into multiple messages

Output¶

WhatsApp Response: Formatted text message sent back to user
Thread Management: Maintains conversation context for follow-up interactions

Error Handling¶

The workflow includes several error handling mechanisms:

Message Processing Errors: The Extract Message Info node wraps processing in try-catch blocks
Safe Node Access: The Prepare Assistant Message node includes safe data retrieval functions
Missing Data Validation: Checks for required thread ID, assistant ID, and message info
Fallback Responses: Provides generic error messages when processing fails
Voice Note Handling: Gracefully handles cases where voice transcription fails

Known Limitations¶

Single Thread Per Interaction: Creates a new thread for each message rather than maintaining conversation history
Response Length: Long responses are split at 1500 characters, which may break context
Voice Note Format: Limited to formats supported by OpenAI Whisper API
Mentor Database: Relies on specific Google Sheets structure and column names
Error Recovery: No retry mechanisms for failed API calls

No related workflows identified from the provided context.

Setup Instructions¶

Import Workflow: Import the JSON into your n8n instance
Configure Credentials:
- Set up Google Service Account credentials for Sheets access
- Configure Twilio API credentials for WhatsApp
- Add OpenAI API key to all HTTP request nodes
Update Configuration:
- Replace <YOUR_OPENAI_API_KEY> in all OpenAI HTTP request headers
- Verify the Assistant ID in the Configuration node
- Confirm the Google Sheets document ID and sheet name
Set Up Webhook:
- Activate the workflow to generate webhook URL
- Configure Twilio WhatsApp webhook to point to the generated URL
- Test with a sample WhatsApp message
Prepare Mentor Database:
- Ensure Google Sheets contains columns: mentor_id, mentor_name, gender, region, position, lesson_name, date_started, date_finished
- Verify the service account has read access to the spreadsheet
Test the Workflow:
- Send a text message to your Twilio WhatsApp number
- Try sending a voice note to test transcription
- Test mentor lookup by including a 6-digit mentor ID in your message