Skip to main content

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 n8n WhatsApp AI Agent stack is composed of eight services, each with a narrow, well-defined responsibility. No single service handles more than one concern — WhatsApp Cloud API manages the connection to Meta’s messaging network, Chatwoot surfaces conversations to human agents, n8n orchestrates all automation logic, PostgreSQL provides durable persistence, Redis holds ephemeral state, Caddy terminates TLS and routes traffic, OpenAI processes language and audio, and Google Drive supplies the canonical client dataset. Understanding what each component owns — and what it explicitly does not own — makes the system easier to operate, debug, and extend.

​
Component overview

ComponentFunctionData handledDependencies
WhatsApp Cloud APIReceives and sends messagesPhone number, text, audio, delivery statusMeta, internet
ChatwootCentralizes conversationsContacts, conversations, agentsPostgreSQL, Redis
n8nExecutes automationsPayloads, context, resultsAll services
OpenAITranscribes and generates responsesText, audio, and sent contextExternal API
PostgreSQLPersistenceClients, folios, memoryDocker volume
RedisTemporary stateBuffers and human-handoff locksDocker volume
Google DriveSync sourceCorporate XLSX fileGoogle OAuth
CaddyReverse proxyHTTPS trafficDNS, ports 80/443

​
Component deep-dives

WhatsApp Cloud API is the Meta-hosted gateway that connects the platform’s phone number to the rest of the stack. It is not a container you deploy — it is a managed service whose credentials and configuration live in the Meta Developer Console.Operational responsibilities:
  • Keep the business phone number active and in good standing with Meta’s policy requirements.
  • Deliver inbound message events to Chatwoot via the registered webhook.
  • Enable sending of text messages, audio files, and images through the Graph API.
  • Rotate access tokens before expiry and audit webhook permissions after any Meta platform update.
The WHATSAPP_GRAPH_API_VERSION and WHATSAPP_PHONE_NUMBER_ID environment variables defined in .env govern which Graph API version and number the workflow targets. Upgrading the API version should be done intentionally and tested against a non-production number first.
Chatwoot is the agent-facing inbox that sits between WhatsApp Cloud API and n8n. Every inbound message from WhatsApp arrives in Chatwoot first; from there, Chatwoot emits webhook events that drive n8n’s automation logic.Operational responsibilities:
  • Present a unified conversation inbox to human support agents.
  • Emit webhook payloads to n8n for every message event — both incoming messages from customers and outgoing messages sent by agents.
  • Differentiate between incoming and outgoing message directions so that n8n can correctly detect human agent intervention.
  • Retain the full visible conversation history so operators can review context without querying the database directly.
Chatwoot stores its own data in the chatwoot PostgreSQL database and uses Redis for ephemeral session and queue data managed by Sidekiq. The CHATWOOT_DOMAIN environment variable controls the public hostname that Caddy routes to Chatwoot.
n8n is the automation engine at the center of the stack. It receives webhook events from Chatwoot and executes a multi-branch workflow that routes messages, applies business rules, queries PostgreSQL, calls OpenAI, and delivers replies via WhatsApp Cloud API.Operational responsibilities:
  • Validate the structure of every incoming Chatwoot payload before processing.
  • Prevent outgoing messages from re-triggering the AI — the msg_from_client node allows only incoming messages to proceed into the AI pipeline.
  • Apply Human Handoff by checking and setting Redis keys before handing off to the AI agent.
  • Buffer and group messages using Redis lists so that rapid successive messages from a customer are processed together.
  • Execute the business-hours schedule, AI agent inference, PostgreSQL client lookups, and WhatsApp reply delivery.
  • Log all executions and errors to the n8n database for operational visibility.
The N8N_DOMAIN environment variable and N8N_ENCRYPTION_KEY are required for the service to start correctly. Credentials for all external services are stored encrypted in the n8n database.
PostgreSQL provides all durable persistence for the platform. A single PostgreSQL instance hosts three logically separate databases, each owned by a different layer of the stack.The three databases:
  • n8n — stores n8n’s internal configuration, encrypted credentials, workflow definitions, and execution history. n8n manages this database entirely; do not modify it manually.
  • chatwoot — stores Chatwoot’s contacts, conversations, agent accounts, and inbox configuration. Chatwoot manages this database via its own migrations.
  • agent — stores the business-specific bd_clientes table and the conversational memory table created by n8n’s Postgres Chat Memory node. This is the only database that operators query directly in normal operation.
The POSTGRES_USER and POSTGRES_PASSWORD values in .env apply to all three databases. The docker/initdb/ scripts create all three databases and the bd_clientes schema the first time the PostgreSQL volume is provisioned.
Redis provides fast, ephemeral state storage for two critical functions: Human Handoff locks and message buffering. It also holds temporary session data used internally by Chatwoot’s Sidekiq workers.Operational responsibilities:
  • Store Human Handoff keys with a TTL of 1800 seconds (30 minutes) so that the AI is silenced while a human agent is active in a conversation.
  • Maintain per-conversation buffer lists that hold incoming messages until the grouping window closes and n8n processes them as a batch.
  • Support Chatwoot’s Sidekiq background job queue, which relies on Redis for job persistence and scheduling.
Redis is secured with the REDIS_PASSWORD environment variable. If Redis becomes unavailable, the safe behavior is to fail closed — the workflow should not auto-respond rather than risk interfering with a human agent conversation.
Caddy is the reverse proxy that terminates HTTPS and routes public traffic to the correct internal service. It is the only container that exposes ports 80 and 443 to the internet.Operational responsibilities:
  • Automatically request and renew TLS certificates from Let’s Encrypt using the LETSENCRYPT_EMAIL address.
  • Route requests to N8N_DOMAIN (e.g. n8n.example.com) to the n8n container.
  • Route requests to CHATWOOT_DOMAIN (e.g. chat.example.com) to the Chatwoot container.
Both domain environment variables must resolve to the host’s public IP before Caddy starts, otherwise ACME certificate issuance will fail. Caddy handles certificate renewal automatically in the background; no manual cron jobs are required.
OpenAI provides two AI capabilities used by the workflow: audio transcription via the Whisper model and conversational response generation via the chat completions API.Operational responsibilities:
  • Transcribe audio messages downloaded from WhatsApp Cloud API into text before the message enters the main processing pipeline.
  • Generate AI agent responses based on the 10-message context window, the system prompt, and any client data retrieved from bd_clientes.
  • Return special image keys that the workflow interprets to select and send the correct price or package image from the URLs defined in .env.
OpenAI is an external API dependency — the workflow cannot complete its AI branch if the API is unreachable or the credential is invalid. The OpenAI credential must be configured in n8n before activating the workflow.
Google Drive hosts the authoritative XLSX spreadsheet that populates the bd_clientes table. Rather than requiring operators to interact with PostgreSQL directly, the business team maintains the client list in a familiar spreadsheet format that n8n syncs on a schedule.Operational responsibilities:
  • Store the XLSX file identified by the GOOGLE_DRIVE_SOURCE_FILE_ID environment variable.
  • Provide access via a Google Drive OAuth2 credential configured in n8n.
  • Serve as the single source of truth for client folio, contact, and payment status data.
The sync branch within the workflow detects changes to the file, downloads it, extracts all rows, and performs an ON CONFLICT (folio) DO UPDATE upsert into bd_clientes. The expected column headers are fixed — any structural change to the spreadsheet requires a matching update to the workflow’s field mapping.

​
Health matrix

Use the following checks to confirm that every service is operating correctly. Run these verifications after initial deployment and after any infrastructure change.
ServiceVerification
CaddyBoth domains respond over HTTPS without certificate errors
n8nWeb interface is accessible and the workflow can be executed manually
ChatwootDashboard is accessible and Sidekiq is processing the job queue
PostgreSQLpg_isready returns success and direct queries return correct results
RedisPING returns PONG when authenticated with REDIS_PASSWORD
OpenAIControlled test with a text message and an audio message both produce valid responses
WhatsAppA real message sent to the business number is received and replied to end-to-end
Run every row in the health matrix immediately after each deployment or configuration change — not just the service you modified. A change to Caddy’s routing can silently break the n8n webhook URL, and a Redis password rotation affects both Human Handoff and the Chatwoot Sidekiq queue.

Build docs developers (and LLMs) love

Get started for freeTalk to us