Skip to content

EXP - WhatsApp Learning Quiz System

An interactive WhatsApp-based educational quiz system that delivers questions via audio and text, evaluates user responses using AI, provides personalized feedback, and tracks learning progress through Airtable integration.

Purpose

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

How It Works

  1. User Registration: When a user sends their first WhatsApp message, the system checks if they exist in the database and creates a new user record if needed
  2. Question Delivery: The system retrieves the current question for the user and sends both text and audio versions via WhatsApp
  3. Response Collection: The workflow pauses and waits for the user's response via webhook
  4. AI Evaluation: User responses are evaluated using OpenAI's GPT model with conversation memory and scoring criteria
  5. Feedback Loop: Based on the evaluation, appropriate feedback is sent back to the user
  6. Progress Tracking: User progress and scores are updated in Airtable
  7. Question Progression: The system either moves to the next question or completes the quiz based on current progress

Workflow Diagram

graph TD
    A[WhatsApp Webhook] --> B[Query User Table]
    B --> C{Is New User?}
    C -->|Yes| D[Create New User Record]
    C -->|No| E[Get Session State]
    D --> F[Get Current Question]
    E --> G[AI Agent]
    F --> H[Send Question Text]
    H --> I[Send Audio]
    I --> J[Respond to Webhook]
    J --> K[Store Resume URL]
    K --> L[Wait for Response]
    L --> M[POST to Resume URL]
    G --> N{Evaluation Logic}
    N --> O[Send Question Text]
    O --> P[Send Audio]
    P --> Q[Update Progress]

Trigger

  • Type: Webhook (WhatsApp)
  • Method: POST
  • Path: /webhook/33898c22-f5f0-45f0-9983-3fd19c2daebb
  • Purpose: Receives incoming WhatsApp messages from Twilio

Nodes Used

Node Type Purpose
Webhook Receives WhatsApp messages from Twilio
HTTP Request Queries and updates Airtable records
Airtable Direct Airtable operations for data management
Twilio Sends WhatsApp messages (text and audio)
AI Agent Evaluates user responses using OpenAI
OpenAI Chat Model Provides AI language processing
Wait Pauses workflow for user responses
If Conditional logic for user flow
Set Data transformation and field mapping
Memory Buffer Maintains conversation context
Respond to Webhook Returns responses to webhook calls

External Services & Credentials Required

Airtable

  • Credential Type: Bearer Token Authentication
  • Required Credentials:
    • Bearer Auth Airtable (ID: 8Ygtj6sT4iF54DV3)
    • Bearer Auth Airtable 2 (ID: WyxGkEYKME2Pvq61)
    • Airtable Personal Access Token (ID: sNS0kFRHVPcpzskN)
  • Base ID: appzp49MGzOjgteaz
  • Tables Used: Users, Questions, User Progress, User Responses

Twilio

  • Credential Type: Twilio API
  • Required Credentials: Waringa (ID: U5YjhGDwBiTlWFNv)
  • Account SID: AC906ca9524b640bdad7d029fd565b6a02
  • WhatsApp Number: +14177633451

OpenAI

  • Credential Type: OpenAI API
  • Required Credentials: OpenAI Assistants API (ID: 1jajeqGzQj9Eb2iW)
  • Model: GPT-4.1-mini

Environment Variables

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

Data Flow

Input

  • WhatsApp Message: Contains user phone number, message body, and profile information
  • Message Structure: 
    1
2
3
4
5
6
7
    {
  "WaId": "254712287952",
  "Body": "User response text",
  "ProfileName": "User Name",
  "From": "whatsapp:+254712287952",
  "To": "whatsapp:+14177633451"
}

Output

  • WhatsApp Messages: Question text, audio files, feedback
  • Airtable Records: User data, progress tracking, response storage
  • Webhook Responses: Status confirmations and resume URLs

Data Transformations

  • Phone number formatting and validation
  • AI evaluation scoring (1-5 scale)
  • Progress calculation and question advancement
  • Resume URL generation for workflow continuation

Error Handling

The workflow includes basic error handling through: - Conditional checks for user existence - Validation of question numbers and progress - Fallback paths for different user states - Most error-prone nodes are currently disabled, suggesting the workflow is in development

Known Limitations

  • Many nodes are disabled, indicating incomplete implementation
  • Limited error handling for API failures
  • No explicit timeout handling for user responses
  • Hard-coded lesson and question limits (Lesson 16, 11 questions max)
  • Resume URL mechanism may not handle concurrent users effectively

No related workflows are explicitly referenced in the current implementation.

Setup Instructions

  1. Import Workflow

    • Import the JSON workflow file into your n8n instance
    • Ensure all required nodes are available in your n8n installation

  2. Configure Credentials

    • Set up Airtable Personal Access Token with read/write permissions
    • Configure Twilio API credentials with WhatsApp messaging enabled
    • Add OpenAI API key with GPT-4 access

  3. Airtable Setup

    • Create base with ID appzp49MGzOjgteaz or update references
    • Set up tables: Users, Questions, User Progress, User Responses
    • Configure proper field types and relationships

  4. Twilio Configuration

    • Set up WhatsApp Business API
    • Configure webhook URL to point to your n8n webhook endpoint
    • Verify phone number formatting and permissions

  5. Testing

    • Enable disabled nodes gradually for testing
    • Test with a known phone number
    • Verify Airtable data flow and AI responses

  6. Production Deployment

    • Enable all necessary nodes
    • Set up proper error handling
    • Configure monitoring and logging
    • Test resume URL functionality thoroughly