Quick Overview

What it is: An n8n workflow that enables AI-first WhatsApp support with seamless human handoff.
Why it’s unique: The AI agent answers queries using RAG (Supabase vector store + Gemini). If a human intervenes, the AI steps down. If there’s no human reply within 2 hours, the AI resumes.
Channel constraints: Respects WhatsApp’s 24-hour customer care window and requires approved message templates for out-of-window messages.

How It Works

AI-first: Incoming WhatsApp messages are routed to an AI agent (Gemini) with knowledge grounded by a Supabase vector store.
Human-in-the-loop: When a human responds in the dashboard, AI pauses for 2 hours for that conversation.
Auto-resume: If no human reply within 2 hours, AI automatically resumes.
Compliance: Only responds within 24 hours of the user’s last message, or via approved templates when outside this window.

Architecture (At a Glance)

Transport: Twilio WhatsApp; n8n http node.
RAG: Supabase (Postgres + embeddings) stores knowledgebase.
LLM: Google Gemini (free API key supported).
Handoff: Human dashboard (GitHub project) logs and labels AI vs Human responses, and controls AI pause/resume.
Prerequisites
n8n (self-hosted or cloud) with public webhook access.
Twilio account with a WhatsApp-enabled number.
Supabase project for vector store.
Google Gemini API key.
Human dashboard: https://github.com/shadrack-ago/whatsapp-dashboard.git
Setup Steps (n8n + Integrations)
Import workflow in n8n
Create new workflow → Import from JSON → Paste the provided JSON.
Enable the workflow.
Create credentials
Twilio: Add TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER. Do NOT paste real secrets publicly.
Gemini: Add GEMINI_API_KEY.
Supabase: Add SUPABASE_URL, SUPABASE_ANON_KEY (or service role where needed), and your table/bucket names.
Connect Twilio WhatsApp
WhatsApp Business setup in Twilio, or Sandbox for testing.
Point Twilio incoming webhook to your n8n webhook URL.
Ensure approved templates for any out-of-window messaging.
Set environment variables (examples)
TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1...
GEMINI_API_KEY=...
SUPABASE_URL=...
SUPABASE_ANON_KEY=...
SUPABASE_TABLE=knowledge_base
EMBEDDING_MODEL
HUMAN_TIMEOUT_MS=7200000 (2 hours)
Human-in-the-loop dashboard
Follow the repo guide: https://github.com/shadrack-ago/whatsapp-dashboard.git
Run the dashboard and connect it to the same conversation store used by the workflow.
Verify that human responses are captured and labeled; confirm AI pause/resume logic.
Supabase for RAG
Create table(s) for documents and embeddings.
Ingest content per this tutorial:Supabase Tutorial
Confirm your n8n nodes query the vector store before calling Gemini.
Gemini setup
Get API key: Gemini API
Set model (e.g., gemini-pro or latest available in your environment).
Test
Send a WhatsApp message to your Twilio number.
Observe AI response.
Trigger a human reply via the dashboard → confirm AI pauses for that thread.
Wait 2 hours or adjust HUMAN_TIMEOUT_MS to test auto-resume.
Customization
Providers: You can swap Twilio for Meta’s WhatsApp Cloud API; keep the 24-hour and template rules.
Tone/Policies: Adjust system prompts and fallback behaviors in the LLM node.
RAG Quality: Tune chunking, TOP_K, and embedding model for better retrieval.
Timeouts: Change HUMAN_TIMEOUT_MS to alter handoff duration.
WhatsApp Policy Notes
24-hour window: Replies must occur within 24 hours of user’s last message; otherwise use an approved template.
Templates: Create and get approval inside Twilio/Meta before sending out-of-window messages.
Security & Reliability
Secrets: Store all keys in n8n credentials or environment variables. Never commit secrets to repos.
Logging: Use the dashboard to audit AI vs Human messages.
Rate limits: Add retry/backoff nodes for Twilio and LLM calls.
Troubleshooting
No replies: Check Twilio webhook URL and n8n workflow is active.
Policy blocks: Ensure template use outside 24-hour window.
Poor answers: Improve RAG data, increase TOP_K, refine prompts.
Handoff not pausing: Verify dashboard is writing the “human active” flag that the workflow reads.
Links
Human dashboard (Full guide): GitHub Repo Link