whatsapp-commerce-agent-kit — WhatsApp AI agent + management panel (n8n)

Free package with the complete stack behind a real production case: an AI-powered WhatsApp customer service agent for e-commerce (Nuvemshop) running on n8n, plus the web management panel for orders and conversations. It ships 44 real production workflows, exported and sanitized (zero secrets), the Next.js panel source, and a .env.local.example documenting every variable and which workflows use it.

Built for a Brazilian jiu-jitsu kimono e-commerce: the store's first WhatsApp agent (v1, on WooCommerce) took 45 days to ship. When the store migrated platforms and the agent died overnight, v2 was rebuilt from zero to production cutover in 7 days — using the governed operating method now published as n8n-governance-kit. This kit is the artifact; that kit is the method.

Portfolio material by Paulo Chaves. The governed way to operate all of this (backup-before-mutation, audit trail, 1-click Railway provisioning) lives in the n8n-governance-kit.

---

What's inside

workflows/            44 JSONs ready to import (no secrets — __VAR__ placeholders)
panel/                Next.js 14 management panel (WhatsApp-Web-like) — env-driven
.env.local.example    every tenant-specific variable + the workflows using it
CREDENTIALS.md        the n8n credentials you need to create (Postgres, Z-API, etc.)
sql/                  the real schema migrations (agent_* tables, guardrails, FAQ, NPS)
scripts/apply-env.sh  swaps every __VAR__ placeholder for your values at once

The 44 workflows by category

Category	Qty	What it does
[Agent]	24	The complete v2 agent: Inbound (debounce, fromMe guard, audio/image), Orchestrator (AI + 11 tools), Formatter, Handoff, Nuvemshop/Correios/FAQ/image/location/contact tools, NPS, health monitor, error handler, WABA inbound
[TEST]	11	Test twins — same topology as production, routed by TEST_PHONE. This is the TEST-first method: validate E2E here before touching production
[Internal]	3	Panel backend: Panel API (read-only), Panel Actions (takeover/send), local orders index (15-min sync, <1s lookup)
[Correios]	3	Bearer token (24h refresh), delivery status reconciler, get token
[Monitor]	2	Quality watchdogs: language audit + fix-regression checks
[Nuvemshop]	1	Store OAuth callback

---

Quickstart

Prerequisites: an n8n instance (self-hosted; Community edition works), Postgres, Redis, and accounts on Z-API + Nuvemshop. Need n8n from scratch on your Railway account? The n8n-governance-kit provisions it in 1 click.

1. Credentials. In n8n (Settings › Credentials) create the credentials from CREDENTIALS.md — Postgres, Redis, Z-API Client-Token, Nuvemshop, OpenAI, Correios. The id in the JSONs is a placeholder; you pick yours on import.
2. Variables. cp .env.local.example .env.local, fill it in, and run ./scripts/apply-env.sh (swaps the __VAR__ placeholders in all 44 JSONs). Or find/replace manually — each var lists the workflows where it appears.
3. Schema. Create the agent_* tables in your Postgres: run the sql/ files in chronological order (conversations, messages, handoffs, chat memory, tool calls, guardrails, FAQ, NPS). The memory table follows the LangChain pattern (session_id TEXT, message JSONB).
4. Import the workflows/*.json into n8n (one by one, or via API).
5. Error workflow. After importing, repoint settings.errorWorkflow of every active workflow to your [Agent] Error Handler (its ID changes on import) — apply-env.sh does this for you via ERROR_HANDLER_WORKFLOW_ID.
6. Z-API webhooks. Point Z-API's "on receive" webhook to [Agent] V2 Inbound. Mind the fromMe loop: don't enable "notify my own sent messages" without the guard (already built into the Inbound).
7. Activate the Error Handler first, the Inbound last. Validate by texting from your TEST_PHONE — it routes to the [TEST] twins.
8. Panel (optional): cd panel, cp .env.example .env.local, fill it in (N8N_PANEL_URL, PANEL_API_KEY = same as the Panel workflows, PANEL_PASSWORD, SESSION_SECRET), npm install && npm run build && npm start.

---

Architecture (summary)

WhatsApp ──Z-API──▶ [Agent] V2 Inbound ──▶ [Agent] V2 Orchestrator ──▶ [Agent] V2 Formatter ──▶ Z-API ──▶ customer
                    (6s debounce,           (AI + 11 tools,              (executes markers:
                     fromMe guard,           Postgres memory)             [[IMG]] [[HANDOFF]]…)
                     audio/image)                  │
                                                   ├─ Nuvemshop (products, orders)
                                                   ├─ Correios (shipping, tracking)
                                                   ├─ FAQ, compare, image, location, contact
                                                   └─ human handoff → Z-API tag + DB status

Principles worth copying (learned in production):

• Side effects are deterministic. The LLM decides what to say; never who to send to nor what media to send. Recipient IDs come from the payload, not from the model.
• The panel never touches the database. Front end → Panel API (n8n, header x-panel-key) → Postgres/Z-API/Nuvemshop. Secrets stay server-side.
• TEST-first. Every [TEST] twin exists to validate with real payloads before production.

---

Security

Every JSON was sanitized: Z-API instance/token/Client-Token, the n8n API key, x-panel-key, phone numbers, store ID, Google place_id and customer PII in sample pinData were replaced with __VAR__ placeholders. The real credentials (Postgres, OpenAI, etc.) were never in the export — n8n stores them encrypted outside the JSON. git grep at will: there are no secrets here.

Credits

• n8n skills used during development derive from n8n-skills (Romuald Członkowski, MIT).
• Governance method and squad format: Synkra AIOS/AIOX framework (MIT).
• Case, workflows and panel: Paulo Chaves.

MIT license. Once imported, the stack is yours — evolve it with Claude Code.