Skip to content

PBA English Version - WhatsApp Teaching Assistant Bot

This workflow provides an AI-powered WhatsApp assistant that helps Rwandan secondary school teachers implement Project-Based Assessment (PBA) effectively. The bot supports both text and voice messages, offering contextual guidance on project instructions, lesson planning, group work, rubrics, grading, and CAMIS integration for Biology, Chemistry, Physics, and Entrepreneurship subjects across Senior 4-6 levels.

Purpose

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

This workflow serves Rwandan secondary school teachers who need practical support implementing Project-Based Assessment (PBA) methodology. Teachers can ask questions about specific projects, get step-by-step guidance for lesson planning, receive help with group work management, understand rubric usage, and learn how to upload marks to CAMIS. The bot provides contextual assistance by accessing a database of PBA projects and a comprehensive knowledge base of teaching resources.

How It Works

  1. Message Reception: Teachers send text messages or voice notes to a WhatsApp number connected to the workflow
  2. Input Processing: The system routes text messages directly while downloading and transcribing voice notes using Google Gemini
  3. Input Unification: All inputs (text or transcribed voice) are consolidated into a standardized format for processing
  4. Logging: User inquiries are logged to Airtable for monitoring and analysis
  5. AI Processing: The PBA Bot agent processes the input using:
    • System prompt with PBA teaching context and conversation flow
    • Airtable tool to retrieve specific project titles and descriptions based on term, grade, and subject
    • RAG system to access detailed PBA resources and best practices
    • Conversation memory to maintain context across interactions
  6. Response Generation: The bot generates contextual responses following a structured menu system
  7. Response Optimization: A summarizer ensures responses stay under 600 characters for WhatsApp compatibility
  8. Response Delivery: The final response is sent back to the teacher via WhatsApp
  9. Response Logging: Bot responses are recorded alongside user inquiries for evaluation
  10. Error Handling: Any errors trigger user notifications and technical team alerts with detailed logging

Workflow Diagram

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

    C -->|Voice Note| D[Download voice notes]
    C -->|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]

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

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

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

    V[PBA Resources] --> W[Default Data Loading]
    W --> X[Recursive Character Text Splitter]
    X --> V
    Y[Embeddings OpenAI] -.-> V
    Y -.-> J
    Z[Reranker for relevant chunks] -.->|AI Reranker| J
    AA[OpenRouter Chat Model] -.->|AI Language Model| M

Trigger

WhatsApp Webhook: Activates when teachers send messages (text or voice) to the connected WhatsApp number. The webhook receives POST requests containing message data including sender information, message type, and content.

Nodes Used

Node Type Node Name Purpose
Webhook WhatsApp Webhook Receives incoming WhatsApp messages
Execute Workflow Call Waiting message Sends immediate acknowledgment to users
Switch Switch for Text and Voice inputs Routes messages based on type (text/audio)
HTTP Request Download voice notes Downloads audio files from WhatsApp
Google Gemini Transcribe a recording Converts voice notes to text
Code Universal input to PBA Support agent Unifies text and transcribed inputs
Airtable Log user inquiry Records user questions for analysis
LangChain Agent PBA Bot Main AI assistant with system prompt and tools
Airtable Tool Get project titles and descriptions Retrieves PBA project information
Vector Store PBA Resources Vectorised Provides RAG-based knowledge retrieval
Memory Context memory Maintains conversation history
LLM Chain Summariser Ensures responses fit WhatsApp limits
Twilio Send WhatsApp response Delivers responses to users
Airtable Record PBA Bot Responses Logs bot responses
Code PBA Bot Error Output Formatting Formats error information
Twilio Send user a message about error Notifies users of errors
Twilio Send PBA bot Error to tech team Alerts technical team
Airtable Log PBA bot error Records error details
Form Trigger PBA Feedback for WhatsApp Collects user feedback

External Services & Credentials Required

  • Twilio: WhatsApp messaging service
    • Account SID and Auth Token
    • WhatsApp-enabled phone number
  • Airtable: Project database and logging
    • Personal Access Token
    • Base ID for PBA Virtual Bot Project
  • OpenRouter: AI language models
    • API key for Claude Haiku and Gemini models
  • Google Gemini: Voice transcription
    • API key for Gemini 3 Flash Preview
  • OpenAI: Text embeddings
    • API key for embedding models
  • Cohere: Text reranking
    • API key for reranker service
  • PostgreSQL: Vector storage
    • Database connection for PBA resources

Environment Variables

No explicit environment variables are defined in this workflow. All credentials are managed through n8n's credential system.

Data Flow

Input: - WhatsApp messages (text or voice notes) - Sender phone number and message metadata

Processing: - Voice notes → transcribed text - Text input → unified format - User queries → logged to Airtable - AI processing with project database and knowledge base access - Response generation and summarization

Output: - WhatsApp responses (≤600 characters) - Logged conversations in Airtable - Error alerts to technical team - Feedback collection through forms

Error Handling

The workflow includes comprehensive error handling:

  1. PBA Bot Errors: If the main AI agent fails, users receive an apology message asking them to retry
  2. Error Categorization: Errors are classified (BAD_REQUEST, TOOL_ERROR, TIMEOUT, AUTH_ERROR, etc.)
  3. Technical Alerts: Detailed error information is sent to the technical team via WhatsApp
  4. Error Logging: All errors are recorded in Airtable with timestamps, user context, and suggested solutions
  5. Graceful Degradation: Users always receive a response, even when the system encounters issues

Known Limitations

  • Responses are limited to 600 characters for WhatsApp compatibility
  • Voice note transcription depends on Google Gemini service availability
  • Project database is limited to specific subjects (Biology, Chemistry, Physics, Entrepreneurship) and grades (Senior 4-6)
  • Bot operates only in English
  • Requires active internet connection for all external service integrations
  • Waiting message: Called to provide immediate acknowledgment to users while processing their requests

Setup Instructions

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

  2. Configure Credentials:

    • Set up Twilio credentials with WhatsApp-enabled number
    • Configure Airtable Personal Access Token
    • Add OpenRouter API key
    • Set up Google Gemini API credentials
    • Configure OpenAI API key for embeddings
    • Add Cohere API key for reranking
    • Set up PostgreSQL database connection

  3. Airtable Setup:

    • Create base with tables: "PBA Projects' Title and Description", "Logs", "PBA Bot Errors"
    • Ensure proper field mapping for project data (Term, Grade, Subject, Title, Description)

  4. Vector Database Setup:

    • Initialize PostgreSQL with pgvector extension
    • Create table "pba_ai_bot" for document storage
    • Upload PBA resources using the document loading nodes

  5. WhatsApp Configuration:

    • Configure Twilio webhook URL pointing to the WhatsApp Webhook node
    • Test message reception and response delivery

  6. Testing:

    • Send test messages to verify text and voice processing
    • Confirm project database queries work correctly
    • Test error handling scenarios
    • Validate feedback form functionality

  7. Monitoring:

    • Set up Airtable views for conversation logs
    • Monitor error logs for system health
    • Review feedback submissions for improvements