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 helps teachers with project instructions, grading rubrics, lesson planning, 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 accessible via WhatsApp, designed to support Rwandan secondary school teachers who are implementing Project-Based Assessment methodology. Teachers can ask questions about specific PBA projects, get guidance on lesson planning, understand grading rubrics, and receive step-by-step implementation support. The system handles both text and voice messages, maintains conversation context, and provides project-specific information by connecting to a comprehensive knowledge base and project database.

How It Works¶

Message Reception: Teachers send questions via WhatsApp (text or voice messages)
Input Processing: Voice messages are transcribed to text, then both input types are unified for processing
Inquiry Logging: All user questions are logged with phone numbers for monitoring and analysis
AI Processing: The PBA Bot analyzes the question using:
- A comprehensive system prompt with PBA teaching guidance
- Access to project titles and descriptions from Airtable database
- RAG (Retrieval Augmented Generation) system with vectorized PBA resources
- Conversation memory to maintain context across interactions
Response Generation: The bot generates contextual responses with specific project guidance
Response Optimization: Responses are summarized to stay under 600 characters for WhatsApp readability
Delivery: The formatted response is sent back to the teacher via WhatsApp
Response Logging: Bot responses are recorded for evaluation and improvement
Error Handling: Any errors are logged and technical team is alerted while user receives a retry message
Feedback Collection: Teachers can provide feedback through an embedded form link

Mermaid Diagram¶

graph TD
    A[WhatsApp Webhook] --> B[Switch for Text and Voice inputs]
    B -->|Voice| C[Download voice notes]
    B -->|Text| D[Universal input to PBA Support agent]
    C --> E[Voice note transcription]
    E --> D
    D --> F[Log user inquiry]
    F --> G[PBA Bot]

    H[Get project titles and descriptions] -->|AI Tool| G
    I[PBA Resources Vectorised] -->|AI Tool| G
    J[Context memory] -->|AI Memory| G
    K[PBA Bot brain] -->|AI Language Model| G

    G -->|Success| L[Summariser]
    G -->|Error| M[Send user a message about error]

    N[Brain for summarization] -->|AI Language Model| L
    L --> O[Send WhatsApp response]
    L --> P[Record PBA Bot Responses]

    M --> 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[PBA Feedback Data]

    V[PBA Resources] --> I
    W[Default Data Loading] -->|AI Document| V
    X[Recursive Character Text Splitter] -->|AI Text Splitter| W
    Y[Embeddings model] -->|AI Embedding| V
    Y -->|AI Embedding| I
    Z[Reranker for relevant chunks] -->|AI Reranker| I

Trigger¶

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

Nodes Used¶

Node Type	Node Name	Purpose
Webhook	WhatsApp Webhook	Receives incoming WhatsApp messages
Switch	Switch for Text and Voice inputs	Routes messages based on type (text/audio)
HTTP Request	Download voice notes	Downloads audio files from WhatsApp
OpenAI	Voice note transcription	Converts voice messages to text
Code	Universal input to PBA Support agent	Unifies text and voice inputs for processing
Airtable	Log user inquiry	Records all user questions for monitoring
LangChain Agent	PBA Bot	Main AI assistant with PBA expertise
Airtable Tool	Get project titles and descriptions	Retrieves project information from database
Vector Store	PBA Resources Vectorised	Searches PBA knowledge base
Memory	Context memory	Maintains conversation history
LLM	PBA Bot brain	Primary language model for responses
LLM Chain	Summariser	Formats responses for WhatsApp
LLM	Brain for summarization	Language model for response formatting
Twilio	Send WhatsApp response	Delivers responses to teachers
Airtable	Record PBA Bot Responses	Logs bot responses for analysis
Form Trigger	PBA Feedback for WhatsApp	Collects user feedback
Airtable	PBA Feedback Data	Stores feedback responses
Code	PBA Bot Error Output Formatting	Processes 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 errors for debugging

External Services & Credentials Required¶

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

Environment Variables¶

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

Data Flow¶

Input: - WhatsApp text messages or voice notes from teachers - Questions about PBA projects, lesson planning, grading, etc.

Processing: - Voice transcription (if applicable) - Input normalization and logging - AI analysis with project database lookup - RAG system search for relevant resources - Response generation with context awareness

Output: - Formatted WhatsApp responses (≤600 characters) - Logged interactions for analysis - Error notifications and alerts - Feedback collection data

Error Handling¶

The workflow includes comprehensive error handling:

PBA Bot Errors: If the main AI agent fails, users receive an immediate retry message
Error Categorization: Errors are classified (timeout, authentication, rate limit, etc.)
Technical Alerts: The technical team receives WhatsApp notifications of errors
Error Logging: All errors are recorded in Airtable with detailed context
User Experience: Users are never left without a response - they either get help or a clear error message

Known Limitations¶

Responses are limited to 600 characters for WhatsApp compatibility
Voice note processing requires stable internet connection
Dependent on external API availability (OpenAI, Twilio, Airtable)
Context memory limited to 20 previous interactions per user
Currently supports only English language responses

No related workflows mentioned in the provided context.

Setup Instructions¶

Import Workflow: Import the JSON 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 database connection
- Add Cohere API key for reranking
Database Setup:
- Create PostgreSQL database with vector extension
- Set up Airtable base with required tables:
  - PBA Projects' Title and Description
  - Logs (for user interactions)
  - PBA Bot Errors
  - Feedback table
Vector Store Preparation:
- Upload PBA resources to the "PBA Resources" node
- Run vectorization to populate the knowledge base
Webhook Configuration:
- Configure Twilio webhook to point to the n8n webhook URL
- Test WhatsApp message reception
Testing:
- Send test messages to verify end-to-end functionality
- Test both text and voice message processing
- Verify error handling and logging
Monitoring Setup:
- Review Airtable logging tables
- Set up monitoring for error notifications
- Configure feedback form access