Customer support WhatsApp bot with Google Docs knowledge base and Gemini AI

Prerequisites

Before you begin, ensure you have the following:

• n8n (self-hosted or cloud) — version 1.0 or later recommended
  • Self-hosted requires Node.js v18.10 or later
  • Or a free/paid account at n8n.cloud
• A Google account with access to Google Docs and Google Drive
• A Meta (Facebook) Developer account for WhatsApp Business API access
• A Google AI Studio account for Gemini API access
• A WhatsApp Business Account (WABA) with a verified phone number
• ngrok or a publicly accessible HTTPS URL (required for WhatsApp webhooks during local development)

---

Get Your API Keys

1. Gemini API Key (Google AI Studio)

1. Go to https://aistudio.google.com/app/apikey
2. Sign in with your Google account
3. Click Create API key
4. Select an existing Google Cloud project or create a new one
5. Copy and save the generated API key securely

2. WhatsApp Business API Credentials

1. Go to https://developers.facebook.com and log in
2. Click My Apps → Create App
3. Select Business as the app type and follow the setup wizard
4. In your app dashboard, find WhatsApp under Add Products and click Set up
5. Navigate to WhatsApp → API Setup
6. Note down:
   • Phone Number ID (shown on the API Setup page)
   • WhatsApp Business Account ID
   • Temporary Access Token (for testing) or generate a Permanent Token via the System User flow at https://business.facebook.com/settings/system-users
7. Under Webhooks, you will need to register a verify token of your own choosing (any random string, e.g., my_verify_token_123) — save this value

3. Google Docs / Drive OAuth Credentials

1. Go to https://console.cloud.google.com
2. Create or select a project
3. Navigate to APIs & Services → Library and enable:
   • Google Docs API
   • Google Drive API
4. Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
5. Set the application type to Web application
6. Add your n8n instance's OAuth callback URL as an authorized redirect URI:

   https://<your-n8n-domain>/rest/oauth2-credential/callback
   

7. Copy the Client ID and Client Secret

---

Installation

Option A — n8n Cloud

1. Log in to https://app.n8n.cloud
2. No local installation is required — skip to Configuration

Option B — Self-Hosted n8n via npm

# Install n8n globally
npm install -g n8n

# Verify installation
n8n --version

Option C — Self-Hosted n8n via Docker

docker pull n8nio/n8n

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

Import the Workflow

Once n8n is running:

1. Open the n8n editor at http://localhost:5678 (or your cloud URL)
2. Click the + (New Workflow) button or go to Workflows → Import
3. Import the workflow JSON file for this integration (download from the project source)
4. Click Save

---

Configuration

Set the following as environment variables before starting n8n (self-hosted), or configure them directly inside n8n credentials for cloud deployments.

| Variable | Description | Where to get it | |----------|-------------|-----------------| | N8N_HOST | The publicly accessible hostname of your n8n instance | Your server/ngrok URL, e.g. https://abc123.ngrok.io | | N8N_PORT | Port n8n listens on (default: 5678) | Set to 5678 unless changed | | GEMINI_API_KEY | API key for Google Gemini AI | Google AI Studio — see step 1 above | | WHATSAPP_ACCESS_TOKEN | Permanent or temporary Meta API access token | Meta Developer portal — see step 2 above | | WHATSAPP_PHONE_NUMBER_ID | The phone number ID tied to your WABA | Meta Developer portal → WhatsApp → API Setup | | WHATSAPP_VERIFY_TOKEN | A secret string you define for webhook verification | Self-defined; must match what you enter in Meta's Webhook config | | GOOGLE_CLIENT_ID | OAuth 2.0 Client ID for Google APIs | Google Cloud Console — see step 3 above | | GOOGLE_CLIENT_SECRET | OAuth 2.0 Client Secret for Google APIs | Google Cloud Console — see step 3 above | | GOOGLE_DOC_ID | The ID of the Google Doc used as the knowledge base | From the Doc's URL: docs.google.com/document/d/<DOC_ID>/edit |

Applying Environment Variables (Self-Hosted)

Create a .env file in your working directory:

# .env
N8N_HOST=https://your-domain.com
N8N_PORT=5678
GEMINI_API_KEY=your_gemini_key_here
WHATSAPP_ACCESS_TOKEN=your_whatsapp_token_here
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_VERIFY_TOKEN=my_verify_token_123
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_DOC_ID=your_google_doc_id

Then start n8n with:

export $(cat .env | xargs) && n8n start

Registering the WhatsApp Webhook

1. In the Meta Developer portal, go to WhatsApp → Configuration → Webhooks
2. Set Callback URL to:

   https://<your-n8n-domain>/webhook/whatsapp
   

3. Set Verify Token to the same value as WHATSAPP_VERIFY_TOKEN
4. Subscribe to the messages webhook field
5. Click Verify and Save

---

Running the Bot

Development Mode (Self-Hosted)

# Start n8n in development mode with verbose logging
N8N_LOG_LEVEL=debug n8n start

Access the editor at: http://localhost:5678

Activate the workflow by toggling the Active switch in the top-right of the workflow editor.

Production Mode (Self-Hosted)

# Start n8n as a background process
n8n start &

# Or with PM2 for process management
npm install -g pm2
pm2 start "n8n start" --name n8n
pm2 save
pm2 startup

n8n Cloud

1. Open the workflow in the n8n editor
2. Toggle the Active switch to enable it — it will begin listening for webhook events immediately

---

Testing

1. Verify the Webhook Endpoint is Reachable

curl -X GET "https://<your-n8n-domain>/webhook/whatsapp\
?hub.mode=subscribe\
&hub.verify_token=my_verify_token_123\
&hub.challenge=test_challenge_string"

Expected response:

test_challenge_string

If you receive test_challenge_string back, the webhook verification is working correctly.

2. Send a Test WhatsApp Message

1. Using the phone number registered in your WABA, send a WhatsApp message to your bot's number (e.g., Hello, what is your return policy?)
2. Watch the n8n Executions panel (Workflows → Executions) for a new execution to appear
3. Confirm the execution shows all nodes completing successfully (green check marks)
4. Verify that a reply is received on WhatsApp containing an AI-generated response drawn from your Google Doc

3. Check the Execution Log

In the n8n editor:

Workflows → Executions → [click latest execution] → inspect each node's input/output

Confirm:

• The WhatsApp Trigger node received the inbound message
• The Google Docs node retrieved content from your knowledge base doc
• The Gemini node returned a non-empty AI response
• The WhatsApp send node returned HTTP 200

---

Troubleshooting

| Problem | Likely cause | Fix | |---------|-------------|-----| | Webhook verification fails with 403 or no response | WHATSAPP_VERIFY_TOKEN mismatch between n8n and Meta portal, or n8n is not publicly reachable | Confirm the verify token strings match exactly (case-sensitive); ensure your n8n URL is publicly accessible and uses HTTPS — use ngrok if testing locally: ngrok http 5678 | | WhatsApp messages are received but no AI reply is sent | Gemini API key is invalid or quota exceeded | Check the Executions panel for errors on the Gemini node; verify the key at aistudio.google.com and confirm you have available quota | | Google Docs node fails with 401 Unauthorized | OAuth token has expired or credentials are misconfigured | Re-authenticate the Google credential in n8n: Credentials → [your Google credential] → Reconnect and complete the OAuth flow again | | Bot replies but does not reference the knowledge base content | Wrong GOOGLE_DOC_ID or the Gemini