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 (text and voice), offers contextual guidance on PBA projects, and maintains conversation memory for personalized assistance.

Purpose

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

This workflow serves as an AI-powered teaching assistant deployed on WhatsApp to support secondary school teachers in Rwanda with PBA implementation. Teachers can ask questions about project instructions, grading rubrics, lesson planning, group work facilitation, and time management in either English or Kinyarwanda. The bot provides step-by-step guidance, retrieves project-specific resources, and helps teachers feel more confident delivering PBA lessons across Biology, Chemistry, Physics, and Entrepreneurship subjects.

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 and translation
  3. Language Handling: A Gemini-powered translator detects the input language (English/Kinyarwanda) and translates Kinyarwanda to English for processing
  4. Query Classification: The system determines if the query needs immediate response or requires database lookup (RAG)
  5. Waiting Message: For complex queries, a contextual waiting message is sent in the user's language
  6. AI Processing: The main PBA Bot agent processes the query using GPT-4, with access to:
    • Airtable tool for project titles and descriptions
    • Vector database (PostgreSQL) for detailed PBA resources
    • Conversation memory for context
  7. Response Generation: The bot generates guidance, which is then summarized to fit WhatsApp's character limits
  8. Language Routing: Responses are translated back to Kinyarwanda if needed and sent via Twilio
  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 Message]
    D --> H[Language Tag Extractor]
    H --> I{Fast or RAG Query?}
    I -->|RAG| J[Send Waiting Message]
    I -->|Fast| K[PBA Bot Agent]
    J --> L[Send Waiting Message via Twilio]
    L --> K
    K --> M[Response Summarizer]
    K -->|Error| N[Bot Error Handler]
    N --> O[Send Error Alert]
    M --> P{English or Kinyarwanda?}
    P -->|English| Q[Send Response in English]
    P -->|Kinyarwanda| R[Translate to Kinyarwanda]
    R --> S[Send Response in Kinyarwanda]

    K -.-> T[Airtable Projects Tool]
    K -.-> U[PBA Resources Vector Store]
    K -.-> V[Simple Context Memory]

    W[Feedback Form] --> X[Store in Airtable]

Trigger

WhatsApp Webhook: Receives incoming WhatsApp messages via Twilio webhook endpoint. Triggers on 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 handling
HTTP Request Downloads voice note files from Twilio
OpenAI (Transcription) Converts voice notes to text using Whisper
LangChain LLM (Gemini) Handles language detection and translation
Code Extracts language tags and formats error outputs
Text Classifier Determines if query needs immediate or RAG response
LangChain Agent Main PBA Bot with system prompt and tools
Airtable Tool Retrieves project titles and descriptions
Vector Store (PostgreSQL) Stores and retrieves detailed PBA resources
Memory (Buffer Window) Maintains conversation context per user
LangChain LLM (GPT-4) Powers the main bot responses and summarization
Twilio Sends WhatsApp responses back to users
Form Trigger Collects user feedback
Airtable Stores feedback and error logs

External Services & Credentials Required

OpenAI API: - Used for voice transcription (Whisper) - Powers GPT-4 chat model for bot responses - Generates embeddings for vector search

Google Gemini API: - Handles language translation between English and Kinyarwanda

Twilio API: - Receives WhatsApp webhooks - Sends WhatsApp messages to users

Airtable API: - Stores PBA project data - Logs feedback and errors - Provides project lookup functionality

PostgreSQL Database: - Stores vectorized PBA resources - Enables semantic search for detailed guidance

Cohere API: - Reranks search results for better relevance

Hugging Face API: - Provides backup translation models

Environment Variables

No explicit environment variables are defined in this workflow. All configurations are handled through n8n credential management for the external services listed above.

Data Flow

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

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

Output: - WhatsApp text responses in user's preferred language - Error messages and alerts - Logged feedback and error data in Airtable

Error Handling

The workflow includes comprehensive error handling:

Transcription Errors: - Catches OpenAI Whisper failures - Logs errors to Airtable with detailed context - Sends user-friendly messages asking to retry

Bot Processing Errors: - Handles AI agent failures and timeouts - Categorizes errors (authentication, rate limits, tool failures) - Sends generic error message to user while logging details

Translation Errors: - Falls back to English if translation fails - Maintains conversation flow despite language processing issues

Network/API Errors: - Retry logic with exponential backoff - Detailed error logging for debugging - User notifications for service unavailability

Known Limitations

  • Voice transcription depends on audio quality and may fail with poor recordings
  • Response length is limited to 600 characters for WhatsApp compatibility
  • Kinyarwanda translation quality may vary for technical educational content
  • Rate limits apply to all external APIs (OpenAI, Gemini, etc.)
  • Vector search accuracy depends on the quality of indexed PBA resources

No related workflows are explicitly mentioned in the current configuration.

Setup Instructions

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

  2. Configure Credentials:

    • Set up OpenAI API credentials for transcription and chat models
    • Configure Google Gemini API for translation
    • Add Twilio credentials for WhatsApp integration
    • Set up Airtable API token for data storage
    • Configure PostgreSQL connection for vector store
    • Add Cohere API for result reranking

  3. Database Setup:

    • Create PostgreSQL database with pgvector extension
    • Set up pba_ai_bot table for vector storage
    • Populate with PBA resource documents

  4. Airtable Configuration:

    • Create base with project data table
    • Set up feedback collection table
    • Configure error logging tables

  5. WhatsApp Integration:

    • Set up Twilio WhatsApp sandbox or approved number
    • Configure webhook URL pointing to the n8n webhook node
    • Test message flow end-to-end

  6. Resource Population:

    • Upload PBA documents to vector store using the data loader nodes
    • Verify project data is properly indexed in Airtable
    • Test tool access from the main agent

  7. Testing:

    • Send test messages in both English and Kinyarwanda
    • Verify voice note transcription works
    • Test error scenarios and logging
    • Validate feedback form integration