Skip to content

setup.md

Latest commit

 

History

History
111 lines (74 loc) · 4.44 KB

setup.md

File metadata and controls

111 lines (74 loc) · 4.44 KB
Raw

Setup

Everything runs on your own computer. Allow about an hour the first time, most of it in Google Cloud.

You need: Docker Desktop, a Google account, Telegram on your phone, and Python 3.10+ (only for the test script).

1. Start n8n

cp .env.example .env

In .env, set N8N_ENCRYPTION_KEY to a long random string and GENERIC_TIMEZONE to your clinic's timezone (for example Asia/Manila). Generate a key with either:

openssl rand -hex 32
$b = New-Object byte[] 32; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); -join ($b | ForEach-Object { $_.ToString('x2') })

Don't change the key later: n8n uses it to encrypt your saved logins.

docker compose up -d

Open http://localhost:5678 and create the owner account.

2. Google Sheet

Create a spreadsheet, rename its tab to Enquiries, paste the line from templates/sheet-columns.csv into A1, and use Data → Split text to columns. The headers should fill A1 to P1.

3. Google sign-in (for Sheets and Gmail)

In Google Cloud Console:

  1. Create a project.

  2. APIs & Services → Library: enable the Google Sheets API, Google Drive API and Gmail API.

  3. Google Auth Platform → Get started: choose External, then under Audience add your own Gmail as a test user.

  4. Clients → Create client → Web application, with this authorized redirect URI:

    http://localhost:5678/rest/oauth2-credential/callback

  5. Keep the Client ID and Client secret somewhere private.

While the app is in Testing mode, Google may ask you to reconnect about once a week.

4. Credentials in n8n

Create these under Create → Credential. The workflow expects these names:

Name Type What you need
Google Sheets - LeadFlow Google Sheets OAuth2 API Client ID and secret from step 3
Gmail - LeadFlow Gmail OAuth2 API The same Client ID and secret
Google Gemini - LeadFlow Google Gemini(PaLM) API A key from https://aistudio.google.com/apikey
Telegram - LeadFlow Telegram API A bot token from @BotFather (/newbot)

When Google says it "hasn't verified this app", choose Advanced → Go to (your app): it's your own app.

5. Your Telegram chat ID

Send your bot any message, then open this in a browser, with your token in place of <TOKEN>:

https://api.telegram.org/bot<TOKEN>/getUpdates

The number after "chat":{"id": is your chat ID.

6. Import the workflow

  1. Import workflows/leadflow-enquiry-triage.json into n8n.
  2. Set Config: replace YOUR_TELEGRAM_CHAT_ID with your chat ID. Adjust the clinic name and office hours if you like.
  3. Append to Sheet and Record Delivery Status: pick your spreadsheet and the Enquiries tab (this replaces YOUR_GOOGLE_SHEET_ID).
  4. Open each node that needs a login and select the matching credential: Gemini Primary, Gemini Backup, both Sheets nodes, Send Staff Alert, Send Acknowledgement.
  5. Save and Publish.

7. Try it

Open http://localhost:5678/form/brightside-enquiry and send an enquiry. To run the full test set:

python scripts/run_samples.py send you@gmail.com
python scripts/run_samples.py check "path/to/downloaded-sheet.csv"

Troubleshooting

Problem Cause and fix
"Service unavailable" in an AI step Google's model is busy (HTTP 503). Retries usually cover it; if it keeps happening, pick another model with free quota at https://aistudio.google.com/rate-limit
"The resource you are requesting could not be found" The model is closed to new users (HTTP 404). Pick another model
The n8n screen only shows a vague AI error Run docker logs leadflow-n8n to see Google's full message
Scripts get HTTP 401 from the form The form's Ignore Bots option. The test script sends a browser-style user agent
A Google node suddenly asks you to sign in again Testing-mode tokens expire after about 7 days. Reconnect the credential
Changes don't reach the live form Click Publish again after saving

Updating the committed workflow

After changing the workflow in n8n: Export JSON, keep the download outside the repo, then run:

python scripts/sanitize_workflow.py "path/to/downloaded-workflow.json"

It swaps private values for placeholders and refuses to save if anything private remains.