Skip to content

PBA English Version

A WhatsApp-based AI assistant that helps Rwandan secondary school teachers implement Project-Based Assessment (PBA) lessons. This workflow provides on-demand support for lesson planning, project guidance, 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 accessible via WhatsApp, designed to make PBA implementation less overwhelming for secondary school teachers in Rwanda. Teachers can ask questions about specific projects, get guidance on lesson planning, understand grading rubrics, and receive practical advice for managing group work and providing effective feedback.

How It Works

  1. Input Processing: Teachers send text messages or voice notes via WhatsApp to the bot
  2. Voice Transcription: Voice messages are automatically transcribed using OpenAI's speech-to-text
  3. Unified Processing: All inputs (text and transcribed voice) are normalized and logged
  4. AI Analysis: The PBA Bot analyzes the query using GPT-4, with access to:
    • Project database (Airtable) containing all PBA project titles and descriptions
    • Vector database (PostgreSQL) with detailed PBA resources, guidelines, and best practices
    • Conversation memory to maintain context across interactions
  5. Response Generation: The bot generates contextual responses based on the teacher's specific needs
  6. Response Optimization: Responses are summarized to fit WhatsApp's character limits while preserving key information
  7. Delivery: The formatted response is sent back to the teacher via WhatsApp
  8. Logging: All interactions and responses are logged for monitoring and improvement

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[Project Database] -->|Tool| G
    I[PBA Resources Vector Store] -->|Tool| G
    J[Context Memory] -->|Memory| G
    K[PBA Bot Brain - GPT-4] -->|LLM| G

    G --> L[Summariser]
    G -->|Error| M[Error Handler]

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

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

    S[Feedback Form] --> T[Store Feedback]

    U[Document Loader] --> V[Text Splitter]
    V --> W[Embeddings Model]
    W --> X[Vector Store Insert]

Triggers

  • WhatsApp Webhook: /webhook/33898c22-f5f0-45f0-9983-3fd19c2daebb - Receives messages from teachers
  • Feedback Form: /form/382926a2-759b-4d36-b3f6-19e4ad830dc2 - Collects user feedback

Nodes Used

Node Type Purpose
Webhook Receives WhatsApp messages via Twilio
Switch Routes text vs voice inputs to different processing paths
HTTP Request Downloads voice message files from Twilio
OpenAI Audio Transcribes voice messages to text
Code Unifies input processing and error handling
LangChain Agent Main PBA Bot with system prompt and tool access
Airtable Tool Retrieves project titles and descriptions
Vector Store (PGVector) Stores and retrieves PBA knowledge base
Memory Buffer Maintains conversation context
OpenAI LLM Powers the bot's reasoning and response generation
Chain LLM Summarizes responses for WhatsApp format
Twilio Sends responses back to teachers via WhatsApp
Airtable Logs interactions, responses, errors, and feedback
Form Trigger Collects structured feedback from users

External Services & Credentials Required

  • Twilio: WhatsApp Business API integration
  • OpenAI: GPT-4 for conversation and transcription
  • Airtable: Project database and logging storage
  • PostgreSQL: Vector database for PBA resources
  • Cohere: Reranking service for improved search relevance

Environment Variables

No specific environment variables are documented in the workflow configuration. Credentials are managed through n8n's credential system.

Data Flow

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

Processing: - Voice transcription and text normalization - Query analysis and context retrieval - AI-powered response generation - Response formatting and summarization

Output: - WhatsApp responses with PBA guidance - Logged interactions in Airtable - Error alerts to technical team - Feedback data collection

Error Handling

The workflow includes comprehensive error handling:

  1. User Notification: Teachers receive immediate feedback when errors occur
  2. Error Categorization: Errors are classified (rate limits, authentication, timeouts, etc.)
  3. Technical Alerts: The tech team receives WhatsApp notifications about critical errors
  4. Error Logging: All errors are logged in Airtable with detailed context
  5. Graceful Degradation: Users can retry their requests after error resolution

Known Limitations

  • Responses are limited to 600 characters for WhatsApp compatibility
  • Voice note processing requires stable internet connectivity
  • The bot operates only in English (this is the legacy version)
  • Rate limits may apply based on OpenAI and other service quotas

This workflow appears to be superseded by a bilingual version that includes Kinyarwanda support. The workflow should be considered deprecated in favor of the newer "PBA with Kinyarwanda" version.

Setup Instructions

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

  2. Configure Credentials:

    • Set up Twilio API credentials for WhatsApp integration
    • Configure OpenAI API key for GPT-4 and transcription
    • Add Airtable API token for database access
    • Set up PostgreSQL credentials for vector storage
    • Configure Cohere API for reranking

  3. Database Setup:

    • Create PostgreSQL database with vector extension
    • Set up Airtable bases for projects, logs, feedback, and errors
    • Populate the vector database with PBA resources

  4. Webhook Configuration:

    • Configure Twilio webhook to point to the n8n webhook URL
    • Set up WhatsApp Business account and phone number

  5. Testing:

    • Test with sample text and voice messages
    • Verify error handling and logging
    • Confirm feedback form functionality

  6. Deployment:

    • Activate the workflow
    • Monitor initial interactions
    • Set up alerting for the technical team

Note: This workflow is marked as deprecated. Consider using the bilingual "PBA with Kinyarwanda" version instead for production deployments.