The n8n WhatsApp AI Agent is a self-hosted automation platform that receives WhatsApp messages, routes them through an AI agent powered by OpenAI, and lets human agents take over from a Chatwoot inbox at any time. The entire stack — n8n, Chatwoot, PostgreSQL, Redis, and Caddy — runs on a single VPS via Docker Compose.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.
Introduction
Understand the platform scope, goals, and the users it serves.
Quickstart
Deploy the full stack on a VPS and send your first automated reply in minutes.
Architecture
Explore how WhatsApp, Chatwoot, n8n, OpenAI, PostgreSQL, and Redis connect.
Configuration
All environment variables and n8n credentials explained.
What this platform does
When a customer sends a WhatsApp message, the platform:- Receives the message via WhatsApp Cloud API into Chatwoot’s inbox
- Checks for human handoff — if a human agent is active, the AI stays silent
- Buffers and deduplicates rapid-fire messages using Redis
- Transcribes audio via OpenAI Whisper if the message is a voice note
- Enforces business hours — sends an informational reply outside working hours
- Queries customer data from PostgreSQL using the conversation folio
- Generates a reply via OpenAI with conversational memory
- Delivers the response back through WhatsApp Cloud API
Core Concepts
Components, workflow logic, human handoff, and the database schema.
Operations
Deployment procedures, day-to-day tasks, backup, and restore.
Security
Secrets management, data privacy, and incident response.
Troubleshooting
Diagnose and fix common failures across every service.
Stack at a glance
| Service | Role | Image |
|---|---|---|
| n8n | Workflow automation & AI orchestration | docker.n8n.io/n8nio/n8n:1 |
| Chatwoot | Agent inbox & webhook source | chatwoot/chatwoot:v4.4.0 |
| PostgreSQL | Customer data & conversation memory | pgvector/pgvector:pg15 |
| Redis | Message buffer & human handoff state | redis:7-alpine |
| Caddy | HTTPS reverse proxy | caddy:2-alpine |
| OpenAI | Text generation & audio transcription | Cloud API |
| WhatsApp Cloud API | Message channel | Meta platform |
This repository contains sanitized templates and an example workflow. Before using it in production you must configure credentials, domains, privacy policies, and validate image versions.