PBA with Kinyarwanda - Bilingual WhatsApp Teaching Assistant¶

A comprehensive bilingual WhatsApp chatbot that provides Project-Based Assessment (PBA) support to secondary school teachers in Rwanda. The bot operates in both English and Kinyarwanda, offering voice note transcription, intelligent query classification, and context-aware responses powered by RAG (Retrieval-Augmented Generation) technology.

Purpose¶

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

This workflow serves as an AI-powered teaching assistant specifically designed for Rwandan secondary school teachers implementing Project-Based Assessment (PBA) lessons. The bot helps teachers navigate PBA implementation by providing contextual guidance, resources, step-by-step procedures, and project-specific support across Biology, Chemistry, Physics, and Entrepreneurship subjects for grades 4-6 across all three terms.

How It Works¶

Message Reception: Teachers send messages via WhatsApp (text or voice notes) through Twilio
Input Processing: Voice notes are transcribed using OpenAI Whisper, while text messages proceed directly
Language Detection: The system detects whether the input is in English or Kinyarwanda and translates Kinyarwanda messages to English for processing
Query Classification: Messages are classified as either "fast" (immediate response) or "RAG" (requires database lookup)
Waiting Message: For complex queries, a contextual waiting message is sent in the teacher's original language
AI Processing: The PBA Bot agent processes the query using conversation memory, Airtable project data, and vector store knowledge
Response Generation: Responses are generated, summarized to 600 characters max, and translated back to the original language if needed
Delivery: Final response is sent via WhatsApp in the teacher's preferred language
Error Handling: Comprehensive error logging and user notifications for any failures
Feedback Collection: Teachers can provide feedback through an integrated form system

Workflow 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 Response]
    L --> J
    I -->|Error| M[Error Handler]
    J --> N[Response Summarizer]
    J -->|Error| O[PBA Bot Error Handler]
    N --> P{Language Routing}
    P -->|English| Q[Send English Response]
    P -->|Kinyarwanda| R[Translate to Kinyarwanda]
    R --> S[Send Kinyarwanda Response]
    O --> T[Send Error to User]
    U[Feedback Form] --> V[Store Feedback in Airtable]

    %% AI Components
    W[OpenAI GPT-4] -.-> J
    X[Google Gemini] -.-> D
    X -.-> K
    X -.-> R
    Y[Airtable Projects DB] -.-> J
    Z[PostgreSQL Vector Store] -.-> J
    AA[Cohere Reranker] -.-> Z

Trigger¶

WhatsApp Webhook: Receives incoming WhatsApp messages via Twilio - Webhook URL: /webhook/33898c22-f5f0-45f0-9983-3fd19c2daebb - Method: POST - Trigger Type: Webhook (currently disabled in workflow)

Feedback Form: Collects user feedback - Form URL: /form/382926a2-759b-4d36-b3f6-19e4ad830dc2 - Method: Form submission

Nodes Used¶

Node Type	Purpose	Count
Webhook	Receive WhatsApp messages	1
Form Trigger	Collect user feedback	1
Switch	Route voice vs text, language routing	2
HTTP Request	Download voice note files	1
OpenAI	Voice transcription	1
LangChain LLM	AI language models (OpenAI GPT-4, Google Gemini)	4
LangChain Agent	Main PBA Bot intelligence	1
LangChain Chain	Translation and message processing	4
Text Classifier	Classify fast vs RAG queries	1
Vector Store	Knowledge retrieval and storage	2
Airtable	Project data and error logging	4
Airtable Tool	Search project details	1
Twilio	Send WhatsApp responses	6
Code	Error handling and data processing	4
Memory	Conversation context storage	2
Embeddings	Text vectorization	1
Document Loader	Process knowledge documents	1
Text Splitter	Chunk documents for processing	1
Reranker	Improve search result relevance	1

External Services & Credentials Required¶

Required Services¶

OpenAI API: GPT-4 model, embeddings, and Whisper transcription
Google Gemini API: Translation and language processing
Twilio: WhatsApp Business API integration
Airtable: Project database and logging
PostgreSQL: Vector store for knowledge base
Cohere: Result reranking for improved search
Hugging Face: Multilingual translation models

Credentials Needed¶

openAiApi - OpenAI API key for GPT-4 and Whisper
googlePalmApi - Google Gemini API credentials
twilioApi - Twilio account SID and auth token
airtableTokenApi - Airtable personal access token
postgres - PostgreSQL database connection
cohereApi - Cohere API key
huggingFaceApi - Hugging Face API token

Environment Variables¶

No explicit environment variables are defined in this workflow. All configuration is handled through n8n credentials and node parameters.

Data Flow¶

Input¶

WhatsApp Messages: Text or voice notes from teachers
Feedback Forms: User satisfaction and improvement suggestions
Knowledge Documents: PBA resources for vector store population

Processing¶

Language Detection: English/Kinyarwanda identification
Voice Transcription: Audio to text conversion
Query Classification: Fast response vs database lookup
Context Memory: 20-message conversation history per user
Knowledge Retrieval: Project-specific guidance from vector store
Response Summarization: 600-character limit enforcement

Output¶

WhatsApp Responses: Contextual guidance in user's language
Error Notifications: User alerts and technical team notifications
Feedback Storage: User satisfaction data in Airtable
Comprehensive Logging: Error tracking and system monitoring

Error Handling¶

The workflow implements comprehensive error handling across multiple failure points:

Transcription Errors¶

Detection: Failed voice note processing
Response: User notification to retry with text
Logging: Detailed error information in Airtable

PBA Bot Errors¶

Detection: AI agent processing failures
Response: Generic error message to user
Logging: Categorized error tracking with suggested solutions

Classification Errors¶

Detection: Query classification failures
Fallback: Route to error handling pipeline
Recovery: Graceful degradation with user notification

Network/API Errors¶

Retry Logic: Automatic retries with exponential backoff
Timeout Handling: Graceful timeout management
Credential Validation: Authentication failure detection

Known Limitations¶

Based on the workflow structure, potential limitations include:

Voice Note Quality: Transcription accuracy depends on audio quality and background noise
Language Mixing: Complex code-switching between English and Kinyarwanda may affect translation quality
Response Length: 600-character limit may truncate complex explanations
Rate Limits: API rate limiting may affect response times during peak usage
Context Window: 20-message memory limit may lose important context in long conversations
Project Coverage: Limited to specific PBA projects in the Airtable database

No related workflows are explicitly mentioned in the provided context.

Setup Instructions¶

1. Import Workflow¶

Copy the workflow JSON
Import into your n8n instance
Ensure all required nodes are available

2. Configure Credentials¶

Set up the following credentials in n8n: - OpenAI API: Add your OpenAI API key - Google Gemini: Configure Google Palm API credentials - Twilio: Add account SID and auth token - Airtable: Create personal access token - PostgreSQL: Set up database connection - Cohere: Add API key for reranking - Hugging Face: Configure API token

3. Database Setup¶

PostgreSQL: Create vector store table pba_ai_bot
Airtable: Set up bases for:
- PBA project data (appntXVw3V83JQuiW)
- Feedback collection
- Error logging

4. WhatsApp Integration¶

Configure Twilio WhatsApp sandbox or production number
Set webhook URL to your n8n instance
Test message reception and response

5. Knowledge Base Population¶

Upload PBA resource documents
Run vector store population process
Verify embeddings are created correctly

6. Testing¶

Send test messages in both English and Kinyarwanda
Test voice note transcription
Verify error handling paths
Test feedback form submission

7. Monitoring¶

Set up Airtable monitoring for errors
Configure alerts for system failures
Monitor API usage and rate limits
Review conversation logs for quality assurance