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.

This guide walks you through a complete first-time installation of the n8n WhatsApp AI Agent platform on a fresh Ubuntu 24.04 LTS VPS. By the end you will have all seven services running behind HTTPS, the n8n workflow imported, and a webhook registered in Chatwoot ready to receive real WhatsApp messages. Before you begin, confirm you have shell access to the target server and that you hold active credentials for Meta (WhatsApp Cloud API), OpenAI, and Google Drive.
1

Confirm requirements

Verify that your server and accounts meet the minimum requirements before proceeding.Server
ResourceMinimum
CPU2 vCPU
RAM4 GB
OSUbuntu Server 24.04 LTS (or compatible)
RuntimeDocker Engine + Docker Compose v2
Network and DNS
  • Two public domains with A/AAAA records pointing to the server’s IP address.
  • Firewall rules allowing inbound traffic on ports 22 (SSH), 80 (HTTP), and 443 (HTTPS).
Third-party credentials
  • Meta WhatsApp Cloud API — approved Business account, Phone Number ID, and Graph API token.
  • OpenAI — API key with access to chat completions and Whisper.
  • Google Drive OAuth2 — service account or OAuth credentials with read access to the data spreadsheet.
The actual capacity required depends on conversation volume, n8n execution retention, and attachment size. The figures above are suitable for a testing environment.
2

Prepare the server

Update all system packages and install the required tooling.
sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl git openssl
Install Docker Engine from its official repository or through your organisation’s approved procedure, then verify both components are present:
docker --version
docker compose version
Avoid running application services as root. If you add your user to the docker group, be aware that group membership grants elevated privileges over the host.
3

Clone the repository

Clone the project to your server and change into the repository root, which is the working directory for all subsequent commands.
git clone <URL_DEL_REPOSITORIO>
cd n8n-whatsapp-ai-agent
4

Configure environment variables

Copy both template files to their active names:
cp .env.example .env
cp docker/docker-compose.yml.example docker/docker-compose.yml
Open .env in your preferred editor and replace every placeholder with a real value. The fields that require attention are:
VariableWhat to supply
N8N_DOMAINYour public n8n domain, e.g. n8n.yourdomain.com
CHATWOOT_DOMAINYour public Chatwoot domain, e.g. chat.yourdomain.com
LETSENCRYPT_EMAILEmail address for Let’s Encrypt certificate notifications
POSTGRES_PASSWORDLong random password for the PostgreSQL superuser
REDIS_PASSWORDLong random password for Redis authentication
N8N_ENCRYPTION_KEYAt least 32 random characters used to encrypt n8n credentials
CHATWOOT_SECRET_KEY_BASELong random secret for Chatwoot session signing
WHATSAPP_PHONE_NUMBER_IDPhone Number ID from the Meta developer dashboard
GOOGLE_DRIVE_SOURCE_FILE_IDFile ID of the Google Drive spreadsheet used as data source
After editing, confirm that no unfilled placeholders remain:
Run the command below and verify the output is empty. Any remaining CHANGE_ME or example.com values will prevent the platform from working correctly in production (unless an example.com URL is intentional for a non-critical variable).
grep -nE 'CHANGE_ME|example\.com' .env
Also review docker/docker-compose.yml to confirm image tags match the versions you have validated.
5

Configure DNS

Create two DNS records pointing to your server’s public IP address:
n8n.example.com   -> IP_DEL_SERVIDOR
chat.example.com  -> IP_DEL_SERVIDOR
Replace example.com with your real domain. After the records propagate, verify resolution from the server:
getent hosts n8n.example.com
getent hosts chat.example.com
Caddy requires public access on ports 80 and 443 to obtain and renew TLS certificates automatically via ACME. Proceed only once both hostnames resolve to the correct IP.
6

Validate the Compose configuration

From the repository root, render the final Compose file and confirm there are no syntax errors, undefined variables, or missing image tags:
docker compose \
  --env-file .env \
  -f docker/docker-compose.yml \
  config
Do not proceed if the output contains empty variable values, YAML errors, or image references that cannot be resolved.
7

Start all services

Bring up the entire stack in detached mode:
docker compose \
  --env-file .env \
  -f docker/docker-compose.yml \
  up -d
Check that every container reaches a healthy or running state:
docker compose \
  --env-file .env \
  -f docker/docker-compose.yml \
  ps
On the first run, Docker creates three PostgreSQL databases (n8n, chatwoot, and agent) using the init scripts in docker/initdb/. These scripts do not re-execute against an existing volume.
8

Review service logs

Inspect the startup output of each service to catch early errors before configuring the application layer:
docker compose --env-file .env -f docker/docker-compose.yml logs --tail=100 postgres
docker compose --env-file .env -f docker/docker-compose.yml logs --tail=100 chatwoot-prepare
docker compose --env-file .env -f docker/docker-compose.yml logs --tail=100 n8n
docker compose --env-file .env -f docker/docker-compose.yml logs --tail=100 caddy
Confirm that PostgreSQL reports all three databases are ready, that chatwoot-prepare completes its migration without errors, that n8n is listening on port 5678, and that Caddy has issued TLS certificates for both domains.
9

Initialise applications

ChatwootOpen https://CHATWOOT_DOMAIN in your browser, create the administrative account, and configure a WhatsApp inbox by following the official Chatwoot documentation. Record the inbox identifier — you will need it when configuring the webhook in Step 11.n8nOpen https://N8N_DOMAIN, create the owner account, and add the following credentials under Settings → Credentials:
Credential typeConnection detail
OpenAIYour OpenAI API key
PostgreSQLHost postgres, database agent, user and password from .env
RedisHost redis, password from .env
WhatsApp Business CloudPhone Number ID and API token from Meta
Google Drive OAuth2OAuth client or service account credentials
10

Import the workflow

In the n8n editor, import the sanitised workflow file:
workflows/atencion-whatsapp-principal.example.json
After importing, complete the following before saving:
  1. Confirm the workflow is deactivated.
  2. Assign every credential to the corresponding node.
  3. Resolve any nodes flagged with an error indicator.
  4. Replace placeholder product names, prices, and URLs with your approved business information.
  5. Verify that the webhook node shows the production URL (/webhook/) and not the test URL (/webhook-test/).
  6. Run manual test executions for each major branch of the workflow.
11

Configure webhooks

Chatwoot must forward conversation events to the n8n production webhook. In Chatwoot, add the following URL as an integration webhook:
https://N8N_DOMAIN/webhook/whatsapp-chatwoot
The production endpoint path is /webhook/whatsapp-chatwoot. The test endpoint /webhook-test/whatsapp-chatwoot is only active while you have the workflow open in the n8n editor. Using the test URL in production will cause messages to be dropped silently.
Also register the webhook URL in the Meta developer dashboard for your WhatsApp application and document the following in your team’s operations inventory:
  • Meta application ID and name
  • WhatsApp Business Account ID
  • Phone Number ID
  • Webhook URL and subscribed events
  • Chatwoot inbox identifier
  • Responsible owner and credential rotation schedule
12

Validate database tables

Confirm that the agent database contains the expected tables created by the init scripts:
docker compose --env-file .env -f docker/docker-compose.yml \
  exec postgres sh -lc 'psql -U "$POSTGRES_USER" -d agent -c "\\dt"'
The output should list at least the tables used by the workflow for business data and conversational memory. If the table list is empty, review the logs from the postgres container and check the init scripts in docker/initdb/.
13

Activation checklist

The workflow must remain deactivated until every item on this checklist is complete.
Activating the workflow before finishing the steps below risks sending malformed responses to real customers, exposing unvalidated business data, or operating without a recovery path. Complete each item in order.
  • Execute the full test plan from docs/pruebas.md and confirm all acceptance cases pass.
  • Review and implement the hardening measures in docs/seguridad.md.
  • Take an initial backup of all Docker volumes.
  • Perform a complete restore from that backup to validate the recovery procedure.
  • Configure basic uptime and disk-space monitoring.
Only after all five items are checked should you activate the workflow in the n8n editor.

Build docs developers (and LLMs) love

Get started for freeTalk to us