The n8n WhatsApp AI Agent is a self-hosted platform that receives WhatsApp conversations, routes them through automated AI workflows, and surfaces them to human agents — all from a single Ubuntu VPS. It is designed for small-to-medium businesses that need to handle repetitive customer enquiries at scale without committing to an external SaaS platform. The stack replaces ad-hoc WhatsApp handling — phone handoffs, copy-pasted answers, and untracked threads — with a coordinated system built on open-source components.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.
The Problem
WhatsApp support typically mixes three kinds of work in an unstructured channel: repetitive questions that could be answered instantly, lookups of business data such as prices or schedules, and conversations that genuinely require a human. Without a coordination layer, response times suffer and customers occasionally receive duplicate or contradictory replies from different team members. There is no shared inbox, no audit trail, and no mechanism to hand a conversation cleanly from a bot to a person.The Solution
The platform centralises every incoming message in Chatwoot and delegates routing decisions to an n8n workflow. For each message, the workflow evaluates a set of ordered conditions to determine the correct action:- Pause the automation entirely while a human agent holds the conversation.
- Buffer the message if the customer sent several in quick succession, grouping them into a single coherent input.
- Transcribe the message if it contains a voice note, using OpenAI Whisper before routing.
- Respond via AI, generating a contextually appropriate reply using conversational memory.
- Query business data stored in PostgreSQL to ground the response in verified information.
- Send a media asset such as a pricing image when the intent matches a known template.
- Queue the message outside business hours and hold it until the next window opens.
agent PostgreSQL database, which is kept in sync from a business-controlled Google Drive spreadsheet.
Scope
What is included:- Docker Compose infrastructure for all services
- WhatsApp Cloud API integration for message ingestion and delivery
- Chatwoot inbox for human agents and conversation history
- n8n principal workflow with AI decision logic
- Google Drive → PostgreSQL data synchronisation workflow
- Conversational memory per contact
- Human Handoff and message buffering via Redis
- Automatic HTTPS via Caddy
- Guides for operations, testing, security, and backup/restore
- An approved Meta Business account or WhatsApp number
- Pre-provisioned domains, VPS, or TLS certificates
- Real credentials of any kind
- Organisation-specific legal or privacy policies
- External monitoring, high availability, or horizontal scaling
- Customer data suitable for testing
Users
The platform is designed around four roles that interact with the system in different ways.| Role | How they interact |
|---|---|
| Customers | Send and receive messages through WhatsApp; never interact with the platform directly |
| Human agents | Monitor and respond to conversations from the Chatwoot inbox |
| Administrators | Maintain n8n workflows, manage credentials, and operate the infrastructure |
| Business owners | Update the Google Drive data source that populates the bd_clientes table |
Success Criteria
The platform is considered correctly deployed when all six of the following conditions hold:- The customer receives a single, coherent response — never a duplicate.
- The automation is fully silent while a human agent has control of a conversation.
- Every data-backed response originates from PostgreSQL, not from AI hallucination.
- Voice messages are either transcribed and processed or fail in a controlled, logged manner.
- No internal service (PostgreSQL, Redis, n8n, Chatwoot) is exposed directly to the internet.
- A new operator can deploy, test, and recover the platform by following the documentation alone.
Before using this platform in production you must supply real credentials (Meta, OpenAI, Google Drive), valid public domains, a configured TLS email address, and any privacy or data-retention policies required by your jurisdiction. The repository ships sanitised templates and a cleaned example workflow — it contains no live secrets or customer data.
Next Steps
Quickstart
Deploy the full stack on a Ubuntu VPS with Docker Compose and send your first automated reply.
Architecture
Understand how WhatsApp Cloud API, Chatwoot, n8n, OpenAI, PostgreSQL, Redis, and Caddy connect.