Skip to content

PBA English Version - WhatsApp Teaching Assistant Bot

This workflow provides a comprehensive WhatsApp-based AI assistant for Rwandan secondary school teachers implementing Project-Based Assessment (PBA). The bot helps teachers with project instructions, lesson planning, group work management, rubrics, grading, and uploading marks to CAMIS across Biology, Chemistry, Physics, and Entrepreneurship subjects for Senior 4-6 students.

Purpose

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

Based on the workflow implementation, this system serves Rwandan secondary school teachers who need practical support implementing Project-Based Assessment methodology. The bot provides contextual guidance for specific PBA projects, helps with lesson planning across different phases (assignment, feedback, presentation), and assists with administrative tasks like uploading marks to CAMIS. Teachers can interact via text or voice messages in English, receiving structured support tailored to their specific term, grade level, and subject area.

How It Works

  1. Input Processing: Teachers send questions via WhatsApp as text or voice messages
  2. Message Routing: The system detects message type and routes voice messages for transcription
  3. Voice Transcription: Voice notes are downloaded and transcribed using Google Gemini
  4. Input Consolidation: All inputs (text/transcribed voice) are unified into a standard format
  5. Logging: User inquiries are logged to Airtable for monitoring and analysis
  6. AI Processing: The PBA Bot agent processes the query using:
    • System prompt with PBA teaching methodology
    • Airtable tool for project titles and descriptions
    • RAG system for detailed PBA resources and best practices
    • Context memory for conversation continuity
  7. Response Generation: The bot generates contextual responses with step-by-step guidance
  8. Response Optimization: Responses are summarized to fit WhatsApp's character limits
  9. Delivery: Final response is sent back to the teacher via WhatsApp
  10. Response Logging: Bot responses are recorded for evaluation and improvement
  11. Error Handling: Any errors trigger user notifications and technical team alerts

Mermaid Diagram

graph TD
    A[WhatsApp Webhook] --> B[Switch for Text and Voice inputs]
    A --> C[Call Waiting message]

    B -->|Voice Note| D[Download voice notes]
    B -->|Text| E[Universal input to PBA Support agent]

    D --> F[Transcribe a recording]
    F --> E

    E --> G[Log user inquiry]
    G --> H[PBA Bot]

    I[Get project titles and descriptions] -->|AI Tool| H
    J[PBA Resources Vectorised] -->|AI Tool| H
    K[Context memory] -->|AI Memory| H
    L[OpenRouter Chat Model1] -->|AI Language Model| H

    H -->|Success| M[Summariser]
    H -->|Error| N[Send user a message about error]

    O[OpenRouter Chat Model] -->|AI Language Model| M

    M --> P[Send WhatsApp response]
    M --> Q[Record PBA Bot Responses]

    N --> R[PBA Bot Error Output Formatting]
    R --> S[Send PBA bot Error to tech team]
    S --> T[Log PBA bot error]

    U[PBA Feedback for WhatsApp] --> V[Feedback Collection]

    W[PBA Resources] --> J
    X[Default Data Loading] --> W
    Y[Recursive Character Text Splitter] --> X
    Z[Embeddings OpenAI] --> W
    Z --> J
    AA[Reranker for relevant chunks] --> J

Trigger

WhatsApp Webhook - Activated when teachers send messages to the configured WhatsApp number. Accepts both text messages and voice notes via Twilio WhatsApp integration.

Nodes Used

Node Type Node Name Purpose
Webhook WhatsApp Webhook Receives incoming WhatsApp messages
Switch Switch for Text and Voice inputs Routes messages based on type (text/audio)
HTTP Request Download voice notes Downloads voice message files from WhatsApp
Google Gemini Transcribe a recording Converts voice messages to text
Code Universal input to PBA Support agent Consolidates text/voice inputs into unified format
Airtable Log user inquiry Records user questions for monitoring
LangChain Agent PBA Bot Main AI assistant with PBA knowledge and tools
Airtable Tool Get project titles and descriptions Retrieves PBA project information
Vector Store PBA Resources Vectorised Provides RAG-based PBA knowledge retrieval
Memory Context memory Maintains conversation history per user
LLM Chain Summariser Optimizes responses for WhatsApp character limits
Twilio Send WhatsApp response Delivers bot responses to users
Airtable Record PBA Bot Responses Logs bot responses for analysis
Error Handling Multiple error nodes Manages failures and alerts technical team
Form Trigger PBA Feedback for WhatsApp Collects user feedback on bot performance
Execute Workflow Call Waiting message Sends immediate acknowledgment to users

External Services & Credentials Required

  • Twilio: WhatsApp Business API integration
  • Airtable: Project database and logging storage
  • OpenRouter: AI model access (Claude Haiku, Gemini Flash)
  • Google Gemini: Voice transcription service
  • Cohere: Text reranking for improved RAG results
  • OpenAI: Text embeddings for vector search
  • PostgreSQL: Vector storage for PBA resources

Environment Variables

No specific environment variables are documented in the workflow. Configuration is handled through n8n credential management for the external services listed above.

Data Flow

Input: WhatsApp messages (text or voice) from teachers asking PBA-related questions

Processing: - Voice messages → transcription → text - Text queries → AI agent processing with tools - Context retrieval from project database and knowledge base - Response generation with PBA-specific guidance

Output: - WhatsApp responses with step-by-step PBA guidance - Logged interactions in Airtable - Error alerts to technical team when needed

Error Handling

The workflow includes comprehensive error handling:

  • User Communication: Immediate error messages sent to users asking them to retry
  • Error Categorization: Automatic classification of error types (timeout, authentication, tool failures, etc.)
  • Technical Alerts: Real-time notifications sent to technical team via WhatsApp
  • Error Logging: Detailed error information stored in Airtable for analysis
  • Graceful Degradation: Bot continues operating even when individual components fail

Known Limitations

Based on the workflow implementation: - Responses are limited to 600 characters for WhatsApp compatibility - Voice transcription depends on Google Gemini service availability - Project information is limited to predefined Airtable database content - Bot operates only in English language - Requires active internet connection for all external service dependencies

  • Waiting message (ID: 7geS92QYmGFUK40m): Provides immediate acknowledgment to users while main processing occurs

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance
  2. Configure Credentials:
    • Set up Twilio account with WhatsApp Business API
    • Create Airtable workspace with required tables (Projects, Logs, Errors, Feedback)
    • Obtain API keys for OpenRouter, Google Gemini, Cohere, and OpenAI
    • Configure PostgreSQL database for vector storage
  3. Webhook Configuration:
    • Configure Twilio webhook to point to the n8n webhook URL
    • Set up WhatsApp phone number routing
  4. Data Preparation:
    • Populate Airtable with PBA project information
    • Load PBA resources into vector database using the document loading nodes
  5. Testing: Send test messages to verify text and voice processing
  6. Monitoring: Set up Airtable views to monitor usage and errors
  7. Feedback Collection: Share feedback form URL with teachers for continuous improvement