The n8n WhatsApp AI Agent is a documented functional base — meaning the architecture is fully defined, the primary workflow has been exported and sanitized, and the infrastructure template is complete enough to stand up a working environment. What it is not yet is a production-validated system: the installation has not been tested on a clean server from scratch, the full integration test suite has not been run, and several security and operational controls are still pending. Treat the current state as a solid starting point that requires deliberate work before it can carry real customer conversations.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/DevMauricio03/n8n-whatsapp-ai-agent/llms.txt
Use this file to discover all available pages before exploring further.
Current maturity level: Documented functional base, pending full validation in a clean environment. The deliverables below are complete; the pre-production checklist must be finished before go-live.
What Is Available
The following deliverables are complete and included in the repository:- Documented architecture — service topology, data flow, and component responsibilities are described in the setup and architecture guides.
- Exported and sanitized primary workflow — the main n8n workflow JSON has been reviewed and no longer contains hardcoded credentials or tokens (the historical token exposure is a separate Git history issue).
- Complete Docker Compose template — a single Compose file brings up the full stack: PostgreSQL, Redis, n8n, Chatwoot, and Caddy.
- PostgreSQL, Redis, n8n, Chatwoot, and Caddy — all five services are configured and wired together in the template.
- Initial
bd_clientesschema — the SQL script that creates the customer and folio database is included and runs automatically on first volume creation. - Installation, operations, testing, and backup guides — step-by-step documentation covers initial setup through routine maintenance.
- Troubleshooting reference — common failure modes for every service are documented with real diagnostic commands.
Pre-Production Checklist
Complete these tasks in order before accepting real customer traffic:- Revoke the historical WhatsApp token that was exposed in Git history and issue a new one.
- Decide whether the repository will be made public; if so, rewrite Git history to remove the exposed token using a tool such as
git-filter-repo. - Test a complete installation from scratch on a clean server to confirm all steps in the setup guide work as documented.
- Confirm that the specific image versions listed in
.env.exampleare mutually compatible and sign off on the validated combination. - Validate the WhatsApp channel configuration in the Chatwoot admin panel — including the webhook URL, verify token, and phone number assignment.
- Implement robust webhook signature verification in the n8n workflow for all incoming Chatwoot and Meta events.
- Separate PostgreSQL users and privileges — create dedicated users for
n8n,chatwoot, andagentdatabases instead of sharing the superuser account. - Add a global error-handling workflow in n8n that catches unhandled exceptions and sends an alert rather than silently failing.
- Configure execution retention limits in n8n and set a memory TTL for AI conversation context to prevent unbounded disk and memory growth.
- Add monitoring and alerting — at minimum, container health checks, disk usage alerts, and a dead-man’s switch for the primary webhook workflow.
- Validate privacy and data-handling requirements with the appropriate legal or compliance stakeholder (see the Security guide for the full list of organizational requirements).
- Run a complete restore drill from a real backup to confirm the backup process produces a recoverable archive.
Technical Risk Matrix
The following risks have been identified during the design and documentation phase. Each has a defined mitigation strategy that should be implemented as part of the pre-production checklist.| Risk | Impact | Mitigation |
|---|---|---|
| Chatwoot payload structure changes in a new version | Workflow nodes that rely on specific field names stop processing messages | Implement contract tests that validate the payload shape before upgrading Chatwoot |
| WhatsApp or OpenAI API token expires or is revoked | Audio transcription and outbound messages fail silently | Implement token rotation procedures and set up expiry alerts |
| Redis becomes unavailable | Human handoff key checks and message buffer logic operate in an unsafe state — AI may respond to conversations assigned to human agents | Design the workflow to fail closed (block AI response) when Redis is unreachable, and add Redis uptime monitoring |
| AI model invents business data | Customers receive incorrect prices, folio statuses, or policy information | Use tool nodes backed by live database queries for all business data; add factual accuracy tests; document prohibited response patterns in the system prompt |
| Disk fills up on the host | PostgreSQL crashes and data is lost | Enforce log and execution retention policies; add disk usage metrics and alerts at the 80% threshold |
| Container image update introduces incompatible change | One or more services become unavailable after an update | Pin exact image tags or digests in .env; maintain a staging environment; document a rollback procedure for each service |
Planned Improvements
These enhancements are out of scope for the initial release but are planned for future iterations:- Separate the customer-service workflow from the data-synchronization workflow — decoupling these two concerns will make each easier to test, deploy, and maintain independently.
- Add a dedicated error and alerting workflow — a centralized error handler will catch failures from all other workflows and route notifications to the appropriate channel (email, Slack, or WhatsApp).
- Use
conversation_idas the Redis and memory key — replacing phone-number-based keys with Chatwoot conversation IDs will correctly isolate concurrent conversations from the same customer. - Add authorization validation before revealing folio details — implement an explicit check that the requesting phone number is associated with the requested folio before returning any sensitive record data.
- Automate linting of Markdown, JSON, and Compose files — add CI checks to catch formatting errors and schema violations in documentation and configuration files before they reach the main branch.
- Add load tests and AI quality metrics — measure response latency under realistic concurrency and track factual accuracy over time to catch regressions introduced by model or prompt changes.