WhatsApp AI Assistant

After this module you can run a WhatsApp assistant that answers questions from your own facts, books jobs step by step, hands chats to a human when needed, and never repeats itself on Meta's webhook retries.

What it does

The demo business is Cool Breeze Heating & Air (Austin). Everything business-specific (FAQ, services, ZIP codes, hours, safety keywords) lives in one Settings node.

Entry	What happens
GET /webhook/wa/inbound	Meta's webhook verification: echoes hub.challenge when hub.verify_token matches, else 403
WhatsApp Trigger or POST /webhook/wa/inbound	One item per incoming message. Rules first: STOP/START, safety keywords (gas, CO), "talk to a person" (handoff, hours-aware), active handoff (bot stays silent), voice notes/media. Everything else → OpenAI reply grounded in Settings, or the rule-based fallback (FAQ, greeting, booking questions one at a time). Saves the conversation, captures the lead (service, ZIP in area, name, preferred time), replies via the WhatsApp node
GET /webhook/wa/conversation?wa_id=…	One conversation: history, lead, handoff, opt-out, 24-hour window
POST /webhook/wa/handoff/release	Staff hand the chat back to the bot

?dry_run=true returns replies without saving or sending; ?now= injects the clock (hours, handoff expiry).

Flow

WhatsApp Trigger / Inbound API ─┐
Verify API ─────────────────────┼→ Settings → Route ─message→ Parse Messages → Any Messages? → Conversation State (dedupe + rules)
Conversation API ───────────────┤                   │          → Use AI? ─yes→ Answer with AI (OpenAI, structured) ─┐
Release Handoff API ────────────┘                   │                    └no──────────────────────────────────────→ Pick Reply → Save Turn
                                                    │          → Dry Run? → Has Reply? → Send WhatsApp Reply → Reply Report → respond / Save Lead / Alert Staff
                                                    ├verify→ Token Matches? → challenge | 403
                                                    ├conversation→ Conversation Status → respond
                                                    └release→ Release Handoff → respond

Verification status (n8n 2.43.6)

• 25 behavior checks (51 assertions) without credentials: webhook verification, parsing (text, batch, voice note, status updates), FAQ/greeting/booking replies, out-of-area ZIP, lead captured once, retried webhook ignored, opt-out/in, safety reply, handoff in/after hours with silence, release and 12 h expiry, dry run saves nothing, AI and send failures reported instead of crashing.
• Not run with OpenAI or WhatsApp credentials (WITH_CREDS=1 TEST_WA_ID=… ./test/test.sh). The AI prompt and structured output have not been checked against a live model, and the WhatsApp Trigger (signature check by n8n) has not received a real Meta webhook.

Files

File	Tier	Purpose
lesson.md	Free	Meta setup, step-by-step build
workflow/starter.json	Free	Triggers, verification, message parsing
workflow/learner.json	Learner	Finished workflow
workflow/code/	Learner	Readable copies of the Code nodes + AI prompt
exercises.md	Learner	Practice tasks
solutions.md	Learner	Exercise solutions
notes.md	Private	Learning log
sell/	Private	Offer, video script, blog post