PBA English Version¶

A WhatsApp-based AI assistant that provides real-time support to secondary school teachers in Rwanda implementing Project-Based Assessment (PBA) lessons. The bot handles both text and voice inquiries, offering contextual guidance on PBA projects, resources, grading, and best practices across Biology, Chemistry, Physics, and Entrepreneurship subjects.

Purpose¶

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

This workflow serves as an intelligent teaching assistant for Rwandan secondary school teachers who need on-demand support while implementing PBA methodology. Teachers can ask questions about specific projects, get guidance on lesson planning, understand grading rubrics, and access resources — all through WhatsApp. The system maintains conversation context and provides project-specific answers by combining a structured project database with a comprehensive knowledge base of PBA materials.

How It Works¶

Input Processing: Teachers send text messages or voice notes to a WhatsApp number, which triggers the workflow via webhook
Voice Transcription: Voice messages are automatically downloaded and transcribed using OpenAI's speech-to-text service
Unified Input: Both text and transcribed voice inputs are normalized into a consistent format for processing
Inquiry Logging: All user questions are logged with phone numbers and timestamps for monitoring and analysis
AI Processing: The PBA Bot agent processes the inquiry using:
- System prompt with detailed PBA teaching guidance
- Airtable tool to retrieve specific project titles and descriptions
- RAG system to access detailed PBA resources and documentation
- Conversation memory to maintain context across interactions
Response Generation: The bot generates contextual responses following a structured conversation flow
Response Summarization: Responses longer than 600 characters are automatically summarized for WhatsApp compatibility
Delivery: The final response is sent back to the teacher via WhatsApp
Response Logging: Bot responses are recorded alongside user inquiries for evaluation
Error Handling: Any failures trigger user notifications and technical team alerts with detailed error logging

Workflow Diagram¶

graph TD
    A[WhatsApp Webhook] --> B[Switch for Text/Voice]
    B -->|Voice| C[Download Voice Notes]
    B -->|Text| D[Universal Input Processor]
    C --> E[Voice Transcription]
    E --> D
    D --> F[Log User Inquiry]
    F --> G[PBA Bot Agent]

    H[Airtable Projects DB] --> G
    I[PBA Resources RAG] --> G
    J[Context Memory] --> G
    K[PBA Bot Brain LLM] --> G

    G -->|Success| L[Response Summarizer]
    G -->|Error| M[Error Handler]

    L --> N[Send WhatsApp Response]
    L --> O[Record Bot Response]

    M --> P[Send Error Message to User]
    M --> Q[Format Error Details]
    Q --> R[Alert Tech Team]
    Q --> S[Log Error to Database]

    T[Feedback Form] --> U[Store Feedback in Airtable]

    V[Document Loader] --> W[Text Splitter]
    W --> X[Embeddings Model]
    X --> Y[Vector Store]
    Y --> I

Trigger¶

WhatsApp Webhook: Activated when teachers send messages to the configured WhatsApp number. Accepts both text messages and voice notes through Twilio's WhatsApp integration.

Nodes Used¶

Node Type	Purpose
Webhook	Receives WhatsApp messages via Twilio
Switch	Routes text vs voice inputs to appropriate processing paths
HTTP Request	Downloads voice message files from Twilio
OpenAI (Transcription)	Converts voice notes to text
Code	Unifies input formats and handles error processing
LangChain Agent	Main PBA Bot with system prompt and tool access
Airtable Tool	Retrieves project titles and descriptions by term/grade/subject
Vector Store (PostgreSQL)	RAG system for detailed PBA resources
Memory Buffer	Maintains conversation context (20 messages)
LLM Chain	Summarizes responses to 600 character limit
Twilio	Sends responses back to teachers via WhatsApp
Airtable	Logs inquiries, responses, feedback, and errors
Form Trigger	Collects user feedback on bot performance

External Services & Credentials Required¶

Twilio: WhatsApp messaging service
- Account SID and Auth Token
- WhatsApp-enabled phone number
OpenAI: Language model and transcription services
- API key for GPT-4 and Whisper models
Airtable: Project database and logging
- Personal Access Token
- Base ID for PBA project workspace
PostgreSQL: Vector database for RAG system
- Connection credentials for vector storage
Cohere: Reranking service for RAG results
- API key for reranker model

Environment Variables¶

No specific environment variables are defined in this workflow. All configurations are handled through n8n's credential system and node parameters.

Data Flow¶

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

Processing: - Voice notes → transcribed text - User inquiries → logged with metadata - Text input → processed by AI agent with access to project database and knowledge base - Agent responses → summarized if needed

Output: - WhatsApp responses to teachers (≤600 characters) - Logged conversation data in Airtable - Error alerts to technical team - Feedback data collection

Error Handling¶

The workflow includes comprehensive error handling:

PBA Bot Failures: If the main agent fails, users receive an immediate apology message asking them to try again
Error Classification: Errors are categorized (Bad Request, Tool Error, Timeout, Auth Error, Rate Limit, etc.)
Technical Alerts: Detailed error information is sent to the technical team via WhatsApp
Error Logging: All errors are logged to Airtable with structured data for analysis
User Experience: Users are never left without a response, even during system failures

Known Limitations¶

Based on the system prompt and workflow design: - Responses are limited to 600 characters for WhatsApp compatibility - Context memory is limited to 20 previous interactions - Voice note processing depends on OpenAI's transcription service availability - The system is designed specifically for Rwandan PBA curriculum and may not generalize to other educational contexts

No related workflows are explicitly mentioned in the current configuration.

Setup Instructions¶

Import Workflow: Import the JSON configuration into your n8n instance
Configure Credentials:
- Set up Twilio credentials with WhatsApp-enabled number
- Add OpenAI API key for GPT-4 and Whisper access
- Configure Airtable Personal Access Token
- Set up PostgreSQL connection for vector storage
- Add Cohere API key for reranking
Prepare Airtable Workspace:
- Create base with tables for: PBA Projects, Logs, Feedback, Errors
- Import PBA project data with Term/Grade/Subject structure
- Set up proper field mappings as defined in workflow nodes
Initialize Vector Database:
- Set up PostgreSQL with vector extension
- Load PBA resources using the document loader nodes
- Verify embeddings are properly stored
Configure WhatsApp:
- Set up Twilio WhatsApp sandbox or production number
- Configure webhook URL pointing to your n8n instance
- Test message delivery both ways
Load Knowledge Base:
- Upload PBA documents, lesson plans, rubrics, and guides
- Run the document processing nodes to populate the vector store
- Verify RAG retrieval is working correctly
Test End-to-End:
- Send test messages to verify text processing
- Test voice note transcription and processing
- Verify error handling and logging
- Test feedback form functionality
Monitor and Maintain:
- Review logs regularly for user patterns and issues
- Update project database as curriculum changes
- Refresh knowledge base with new PBA resources
- Monitor error rates and response quality