Skip to content

PBA English Version

A WhatsApp-based AI assistant that helps Rwandan secondary school teachers implement Project-Based Assessment (PBA) lessons. The bot provides contextual guidance, resources, and step-by-step procedures for Biology, Chemistry, Physics, and Entrepreneurship across all senior grades and terms.

Purpose

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

Based on the workflow implementation, this system serves as a virtual teaching assistant for secondary school teachers in Rwanda who are implementing Project-Based Assessment (PBA) methodology. The bot helps teachers with lesson planning, project guidance, grading rubrics, time management, and resource access through an accessible WhatsApp interface.

How It Works

  1. Input Reception: Teachers send text messages or voice notes to a WhatsApp number
  2. Message Processing: Voice notes are transcribed to text, and all inputs are normalized
  3. Inquiry Logging: User questions and phone numbers are logged for monitoring
  4. AI Processing: The PBA Bot analyzes the input using:
    • System prompts with PBA teaching methodology
    • Airtable database for project titles and descriptions
    • Vector database (RAG) for detailed project resources
    • Conversation memory for context-aware responses
  5. Response Generation: AI generates helpful guidance based on the teacher's specific needs
  6. Response Optimization: Long responses are summarized to fit WhatsApp's character limits
  7. Delivery: The response is sent back to the teacher via WhatsApp
  8. Feedback Collection: Teachers can provide feedback through an embedded form link

Workflow Diagram

graph TD
    A[WhatsApp Webhook] --> B[Switch for Text/Voice]
    B -->|Voice| C[Download Voice Notes]
    B -->|Text| D[Universal Input Processor]
    C --> E[Voice Transcription]
    E --> D
    D --> F[Log User Inquiry]
    F --> G[PBA Bot Agent]

    H[Airtable Projects DB] --> G
    I[PBA Resources Vector Store] --> G
    J[Context Memory] --> G
    K[PBA Bot Brain - GPT-4] --> G

    G -->|Success| L[Response Summarizer]
    G -->|Error| M[Error Handler]

    L --> N[Send WhatsApp Response]
    L --> O[Record Bot Response]

    M --> P[Send Error Message to User]
    M --> Q[Alert Tech Team]
    M --> R[Log Error Details]

    S[Feedback Form] --> T[Store Feedback in Airtable]

Trigger

WhatsApp Webhook: Activated when users send messages to the configured WhatsApp number via Twilio. Accepts both text messages and voice notes.

Nodes Used

Node Type Purpose
Webhook Receives incoming WhatsApp messages from Twilio
Switch Routes text vs voice inputs to appropriate processing paths
HTTP Request Downloads voice note files from Twilio
OpenAI Audio Transcribes voice notes to text
Code Unifies text/voice inputs and formats error handling
Airtable Logs inquiries, responses, errors, and feedback
Airtable Tool Retrieves PBA project titles and descriptions
Vector Store (PGVector) Stores and retrieves PBA teaching resources
LangChain Agent Main AI bot with system prompts and tool access
LangChain LLM GPT-4 models for bot reasoning and response summarization
Memory Buffer Maintains conversation context (20 message window)
Form Trigger Collects user feedback
Twilio Sends responses back to users via WhatsApp

External Services & Credentials Required

  • Twilio: WhatsApp Business API integration
    • Account SID
    • Auth Token
    • WhatsApp-enabled phone number
  • OpenAI: AI language models and transcription
    • API Key (for GPT-4 and Whisper)
  • Airtable: Project database and logging
    • API Key
    • Base ID for PBA projects workspace
  • PostgreSQL: Vector database for RAG
    • Connection string with pgvector extension
  • Cohere: Text reranking for improved search results
    • API Key

Environment Variables

The workflow requires these credentials to be configured in n8n: - TWILIO_ACCOUNT_SID - TWILIO_AUTH_TOKEN - OPENAI_API_KEY - AIRTABLE_API_KEY - POSTGRES_CONNECTION_STRING - COHERE_API_KEY

Data Flow

Input: - WhatsApp text messages or voice notes from teachers - Feedback form submissions

Processing: - Voice notes → transcribed text - Text queries → AI analysis with PBA context - Project lookups → Airtable database queries - Detailed guidance → Vector database searches

Output: - WhatsApp responses with PBA guidance (≤600 characters) - Logged conversations in Airtable - Error alerts to technical team - Feedback data for system improvement

Error Handling

The workflow includes comprehensive error handling:

  1. User Notification: Users receive immediate error messages asking them to retry
  2. Technical Alerts: Error details are sent to the technical team via WhatsApp
  3. Error Logging: All errors are categorized and logged in Airtable with:
    • Error type (timeout, authentication, tool failure, etc.)
    • User context and input
    • Suggested solutions
    • Timestamp and severity level
  4. Graceful Degradation: Bot continues operating even if individual components fail

Known Limitations

  • Responses are limited to 600 characters for WhatsApp compatibility
  • Voice note processing requires additional latency for transcription
  • Conversation memory is limited to 20 previous interactions
  • Currently supports only English language responses
  • Requires stable internet connection for all external API calls
  • PBA Feedback Form (integrated within this workflow)
  • Document vectorization pipeline (for updating the knowledge base)

Setup Instructions

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

  2. Configure Credentials:

    • Set up Twilio credentials with WhatsApp Business API access
    • Add OpenAI API key with GPT-4 and Whisper access
    • Configure Airtable API key and base access
    • Set up PostgreSQL database with pgvector extension
    • Add Cohere API key for reranking

  3. Database Setup:

    • Create Airtable base with tables for: Projects, Logs, Feedback, Errors
    • Set up PostgreSQL table pba_ai_bot for vector storage
    • Load PBA documents into the vector store

  4. WhatsApp Configuration:

    • Configure Twilio webhook URL to point to the n8n webhook endpoint
    • Test message delivery and reception

  5. Testing:

    • Send test messages to verify text and voice processing
    • Test error scenarios to ensure proper handling
    • Validate feedback form functionality

  6. Monitoring:

    • Set up alerts for error notifications
    • Monitor Airtable logs for usage patterns
    • Review feedback data for system improvements

  7. Deployment:

    • Activate the workflow
    • Share WhatsApp number with target teachers
    • Provide user documentation and training materials