Skip to content

PBA with Kinyarwanda - WhatsApp Teaching Assistant Bot

A bilingual WhatsApp chatbot that provides on-demand support to Rwandan secondary school teachers implementing Project-Based Assessment (PBA) lessons. The bot handles both English and Kinyarwanda inputs, offers contextual guidance on PBA projects, and helps teachers with lesson planning, grading, feedback strategies, and resource access.

Purpose

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

Based on the workflow implementation, this bot serves Rwandan secondary school teachers who need immediate support while implementing PBA lessons across Biology, Chemistry, Physics, and Entrepreneurship subjects for grades Senior 4-6. Teachers can ask questions in either English or Kinyarwanda and receive practical, actionable guidance for their specific projects and teaching challenges.

How It Works

  1. Message Reception: Teachers send WhatsApp messages (text or voice) to the bot via Twilio webhook
  2. Input Processing: Voice messages are transcribed using OpenAI Whisper, then all inputs are processed through language detection
  3. Language Translation: Kinyarwanda messages are translated to English for processing, with language tags preserved for response routing
  4. Query Classification: Messages are classified as either "fast" (immediate response) or "RAG" (requires database lookup)
  5. Waiting Message: For complex queries, a contextual waiting message is sent in the user's language
  6. AI Processing: The PBA Bot agent processes the query using OpenAI/OpenRouter models with access to:
    • Airtable tool for project titles and descriptions
    • Vector database (PostgreSQL) for detailed PBA resources and guidance
  7. Response Generation: Comprehensive responses are generated and summarized to under 600 characters
  8. Language Routing: Responses are sent in the original language (English directly, or translated back to Kinyarwanda)
  9. Error Handling: Comprehensive error logging and user-friendly error messages for various failure scenarios
  10. Feedback Collection: Users can provide feedback through an integrated form system

Mermaid Diagram

graph TD
    A[WhatsApp Webhook] --> B{Voice or Text?}
    B -->|Voice| C[Download Voice Note]
    B -->|Text| D[Kinyarwanda Translator]
    C --> E[Transcribe Voice Note]
    E --> D
    E -->|Error| F[Transcription Error Handler]
    F --> G[Send Error Alert]
    D --> H[Language Tag Extractor]
    H --> I[Text Classifier]
    I -->|Fast Query| J[PBA Bot]
    I -->|RAG Query| K[Send Waiting Message]
    K --> L[Send Waiting Message via Twilio]
    L --> J
    J --> M[PBA Bot Response Summarizer]
    J -->|Error| N[PBA Bot Error Handler]
    N --> O[Send User Error Message]
    M --> P{Language Tag?}
    P -->|English| Q[Send Bot Response in Eng]
    P -->|Kinyarwanda| R[Eng to Kin Translator]
    R --> S[Send Bot Response in Kinyarwanda]

    J -.-> T[Search PBA Project Details - Airtable]
    J -.-> U[PBA Resources Vectorised - PostgreSQL]
    J -.-> V[Simple Context Memory]

    W[PBA Feedback Form] --> X[PBA Feedback Data - Airtable]

Trigger

WhatsApp Webhook: Receives incoming WhatsApp messages via Twilio webhook endpoint. The webhook is configured to handle both text messages and voice notes from teachers.

Nodes Used

Node Type Purpose
Webhook Receives WhatsApp messages from Twilio
Switch Routes between voice and text message paths
HTTP Request Downloads voice note files from Twilio
OpenAI (Transcribe) Converts voice messages to text
LangChain Agent Main PBA teaching assistant bot with tools
Text Classifier Determines if query needs fast or RAG response
Chain LLM Language translation and message composition
Code Error handling and data formatting
Twilio Sends WhatsApp responses back to users
Airtable Stores feedback data and project information
Airtable Tool Retrieves PBA project titles and descriptions
Vector Store (PostgreSQL) Stores and retrieves detailed PBA resources
Memory (Buffer Window) Maintains conversation context per user
Form Trigger Collects user feedback

External Services & Credentials Required

  • OpenAI API: For voice transcription, language models, and embeddings
  • Twilio: For WhatsApp message sending/receiving
  • Airtable: For project data storage and feedback collection
  • PostgreSQL: For vector database storage of PBA resources
  • Cohere: For result reranking in RAG queries
  • OpenRouter: Alternative language model provider
  • Google Gemini: Additional language model for translations
  • Hugging Face: For specialized multilingual models

Environment Variables

No explicit environment variables are defined in this workflow. All external service configurations are handled through n8n credential management.

Data Flow

Input: - WhatsApp text messages or voice notes from teachers - Messages can be in English or Kinyarwanda - Queries about PBA projects, grading, feedback, lesson planning

Processing: - Voice → Text transcription - Language detection and translation - Query classification and routing - AI agent processing with tool access - Response generation and summarization

Output: - WhatsApp responses in the user's original language - Contextual PBA guidance and resources - Error messages for failed operations - Feedback collection for service improvement

Error Handling

The workflow includes comprehensive error handling:

  1. Transcription Errors: Voice processing failures are logged to Airtable and users receive fallback messages
  2. PBA Bot Errors: Agent failures trigger user notifications and detailed error logging
  3. Classification Errors: Text classifier failures route to error handling with retry logic
  4. Translation Errors: Language processing issues are handled gracefully
  5. External Service Failures: API timeouts and authentication errors are captured and logged

All errors include: - User phone number tracking - Timestamp logging - Error categorization - WhatsApp alert messages - Detailed technical logs for debugging

Known Limitations

  • Voice message processing depends on OpenAI Whisper API availability
  • Response length is limited to 600 characters for WhatsApp compatibility
  • Kinyarwanda translation quality depends on model performance
  • Vector database queries may have latency for complex searches
  • Rate limiting may affect high-volume usage periods

No related workflows are explicitly mentioned in the current implementation.

Setup Instructions

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

  2. Configure Credentials:

    • Set up OpenAI API credentials for transcription and language models
    • Configure Twilio credentials for WhatsApp integration
    • Add Airtable Personal Access Token for data storage
    • Set up PostgreSQL credentials for vector database
    • Configure Cohere API for result reranking
    • Add OpenRouter and Google Gemini credentials as needed

  3. Database Setup:

    • Create PostgreSQL database with pgvector extension
    • Set up Airtable bases for feedback and project data
    • Populate vector database with PBA resource documents

  4. Webhook Configuration:

    • Configure Twilio WhatsApp webhook to point to the n8n webhook URL
    • Set up proper webhook authentication and validation

  5. Resource Loading:

    • Upload PBA resource documents through the Default Data Loader
    • Ensure project data is properly structured in Airtable

  6. Testing:

    • Test voice message transcription
    • Verify language translation functionality
    • Test both English and Kinyarwanda conversation flows
    • Validate error handling paths

  7. Activation:

    • Enable the workflow
    • Monitor initial usage and error logs
    • Collect user feedback for improvements