AI Lead Response & Qualification Concierge

Download

Production bundle

Download and import all three production workflows. They work together and should be kept on the same version. The ZIP also contains three optional setup/test helpers and a sanitized Docker Compose baseline; they are included so every file referenced by this guide is available from the same release.

Importing a workflow does not import working secrets. Reconnect every credential and replace every environment-specific ID before publishing.

Optional helper files

The helper workflows import unpublished. Keep them unpublished: run them manually only during setup or controlled tests.

06-docker-compose.yml is not an n8n workflow. It is an optional self-hosting baseline with a persistent volume and production-oriented execution settings. Replace n8n.example.com and UTC, then provide your own stable HTTPS reverse proxy or tunnel before enabling Telegram webhooks.

Files excluded from public cards

• the internal pre-production backup is an internal backup, not the supported template.
• Local credential exports, execution exports, .env files, database volumes, and screenshots containing identifiers must never be offered.

Compatibility

• Built and tested with n8n 2.30.5.
• Uses built-in n8n Form, Schedule Trigger, Google Sheets, Telegram, Telegram Trigger, Send Email, Gmail, Code, If, and Error Trigger nodes.
• The included JSON uses NVIDIA Nemotron. You may replace that model subnode with OpenAI, Anthropic, OpenRouter, Gemini, or another n8n-compatible chat model while preserving the structured output contract.
• The default connected email path is Send Email/SMTP. Gmail is present but disconnected.

If a newer n8n release shows a node migration warning, duplicate the imported workflows, accept migrations in the duplicates, and run the full test matrix before replacing the originals.

Public-release security check

n8n workflow exports can contain credential names and IDs, even though they do not contain the stored secret itself. Before publishing a release:

1. Replace personal credential names with generic names.
2. Remove or replace real chat IDs, spreadsheet IDs, sender addresses, form URLs, and tunnel domains.
3. Inspect HTTP Request nodes for copied authentication headers.
4. Search for common secret prefixes and the words token, secret, password, authorization, and apiKey.
5. Import the sanitized files into a clean n8n instance and confirm every credential is visibly unconnected.

Suggested release package

ai-lead-concierge-v0.4/
├── 00-production-error-handler.json
├── 01-ai-lead-concierge.json
├── 02-telegram-approval-dispatcher.json
├── 03-google-form-builder.json
├── 04-telegram-keyboard-smoke-test.json
├── 05-error-handler-smoke-test.json
├── 06-docker-compose.yml
├── README.md
└── release-manifest.json

The website can expose individual JSON buttons and one ZIP button. Version the ZIP and all three JSON files together so users do not combine incompatible releases.

License and support copy

The release does not claim to include a separate license file. Usage and support notice:

Free template for personal and commercial implementation. Third-party service charges, account limits, and compliance obligations remain the user's responsibility. No uptime or deliverability warranty is included.

Install

Before you begin

Prepare these items:

• an n8n instance you can administer;
• a public HTTPS n8n URL if you are self-hosting;
• the three production JSON files;
• a Telegram account and bot token;
• a Google account with access to the Form and response spreadsheet;
• a credential for an n8n-compatible chat-model provider; the included workflow is prewired for NVIDIA Nemotron;
• SMTP host, port, username, password/app password, and verified sender address.

Allow approximately 45–90 minutes for a first installation, excluding Google OAuth verification or DNS changes.

Step 1 — Run n8n

Option A: n8n Cloud

Create an n8n Cloud workspace and continue to Step 2. Cloud supplies the public HTTPS URL and supports managed Google OAuth for Google Sheets.

Option B: Docker/self-hosted

Use the included 06-docker-compose.yml or your own supported n8n deployment. The included baseline uses a persistent named volume and pins n8n 2.30.5. Before starting it, replace n8n.example.com with your stable HTTPS domain and change UTC if the installation needs another timezone.

Minimum checks:

docker --version
docker compose version
docker compose -f 06-docker-compose.yml up -d
docker compose -f 06-docker-compose.yml ps

Open http://localhost:5678 only for local administration. Telegram Trigger production webhooks require a stable public HTTPS address such as https://n8n.example.com/.

If a reverse proxy or tunnel exposes n8n, configure at least:

WEBHOOK_URL=https://n8n.example.com/
N8N_EDITOR_BASE_URL=https://n8n.example.com/
N8N_PROXY_HOPS=1
GENERIC_TIMEZONE=Africa/Lagos
TZ=Africa/Lagos

Replace the domain and timezone. Restart the container after changing environment variables. A temporary Quick Tunnel is acceptable for testing but its URL can change; use a named tunnel or normal reverse proxy for a persistent demo.

Preserve the n8n data volume. Do not run docker compose down -v unless you explicitly intend to erase workflows, credentials, users, and the encryption key.

Step 2 — Import the workflows

In n8n:

1. Create a project or open the personal workspace.
2. Create a new workflow.
3. Open the workflow menu in the upper-right.
4. Choose Import from File.
5. Import 00-production-error-handler.json.
6. Repeat for 01-ai-lead-concierge.json.
7. Repeat for 02-telegram-approval-dispatcher.json.
8. Keep all three unpublished until configuration and tests are complete.

Expected names:

• 00 - Production Error Handler (Telegram)
• 01 - AI Lead Response & Qualification Concierge [MVP]
• 02 - Telegram Approval & Email Dispatcher

If n8n assigns new workflow IDs and the error workflow reference does not resolve, open Settings in workflows 01 and 02 and select workflow 00 in Error workflow.

Step 3 — Create credentials

Create and test these credentials in n8n:

1. Telegram API bot token — required by all three workflows.
2. Google Sheets OAuth2 — required by workflows 01 and 02.
3. Your chosen chat-model provider — required by workflow 01. The imported template initially contains an NVIDIA Nemotron model node; replace that subnode if you use another provider.
4. SMTP account — required by workflow 02’s default email path.
5. Gmail OAuth2 — optional and only needed if you switch providers.

Follow the Credentials tab before selecting credentials on individual nodes.

Step 4 — Build the Google assets

1. Create the AI Automation Enquiry Google Form using the exact field labels in the Form & Sheets tab.
2. Publish it to the intended audience.
3. Link responses to a Google spreadsheet.
4. Add a second sheet tab named Workflow Report.
5. Paste the 26 report headers into row 1 in the exact order provided.
6. Copy the spreadsheet ID, response sheet ID, and report sheet ID from their URLs.

Step 5 — Configure environment-specific values

Replace every placeholder or demo value listed in the Configure tab. At minimum:

• Telegram owner chat ID and allowed Telegram user ID;
• Telegram credential on all Telegram nodes;
• Google credential and spreadsheet/sheet IDs on all Google Sheets nodes;
• chosen LLM credential and model;
• SMTP credential and verified From address;
• workflow timezone;
• error workflow reference.

Step 6 — Confirm provider wiring

The supported default is:

Prepare Email Payload → Send via SMTP → Capture Email Delivery

Send via Gmail must remain unconnected beside it. Do not add an IF node asking which provider to use. To switch providers, disconnect SMTP, connect Gmail in the same position, configure Gmail, and retest all email paths.

Step 7 — Test while unpublished

Run the manual sample first. Then test Telegram, the Google Form poller, and the three owner decisions using tester-owned email addresses. Follow the Test tab exactly.

Step 8 — Publish in this order

1. Publish 00 - Production Error Handler (Telegram).
2. Publish 02 - Telegram Approval & Email Dispatcher.
3. Confirm it is the only active Telegram Trigger using this bot.
4. Publish 01 - AI Lead Response & Qualification Concierge [MVP].
5. Submit one final Google Form test and complete a Reject path.

Installation complete when

• all three workflows show no missing credential warning;
• the dispatcher’s Telegram Trigger displays the correct production webhook;
• a manual lead reaches Telegram and creates one report row;
• Approve and Edit reply send only to a tester-owned address;
• Reject records the action without sending email;
• a controlled error reaches the owner chat;
• a second lead can enter while the first is still pending.

Official references

• n8n: Export and import workflows
• n8n: Docker Compose deployment
• n8n: Configure webhook URLs behind a reverse proxy

Credentials

Store all secrets in n8n’s credential manager. Never paste a token, API key, OAuth secret, or SMTP password into a Code node, Set node, sticky note, downloadable JSON, screenshot, or website field.

Telegram

Create the bot

1. Open Telegram and start a chat with BotFather.
2. Send /newbot.
3. Choose a display name.
4. Choose a unique username ending in bot.
5. Copy the token BotFather returns and store it temporarily in a password manager.
6. Open the new bot’s chat and press Start or send /start.

Create the n8n credential

1. In n8n, open Credentials and choose Telegram API.
2. Paste the BotFather access token.
3. Name the credential something generic, such as Telegram Owner Bot.
4. Save and run the credential test.

Find and restrict the owner ID

Use a temporary Telegram Trigger test or a disposable workflow:

1. Add a Telegram Trigger with the new credential.
2. Listen for a test event.
3. Send a plain message to the bot.
4. Inspect message.chat.id and message.from.id in the trigger output.
5. Save the numeric value as <OWNER_CHAT_ID> and <OWNER_USER_ID>.
6. Delete or disable the temporary trigger before publishing the dispatcher.

For a private owner chat, the chat and user ID are commonly the same. Enter both explicitly in the dispatcher trigger restrictions.

Apply the credential and ID to:

• workflow 00: Send Error Alert to Owner;
• workflow 01: the included Notify NVIDIA Failure (Telegram) node and Send Telegram Review Message;
• workflow 02: Telegram Owner Response, Request Edited Reply, and Send Owner Status.

Only workflow 02 may own the active Telegram Trigger for this bot. The other workflows send messages but do not receive updates.

Telegram security

• Treat the bot token like a password; revoke it in BotFather if exposed.
• Restrict the Telegram Trigger to the owner chat and user IDs.
• Do not add the bot to public groups for this workflow.
• Do not forward approval messages to other users; callbacks are matched to a pending lead and owner identity.

Google OAuth

The workflow uses Google Sheets for intake polling, approval state, and reporting.

n8n Cloud

1. Create a Google Sheets OAuth2 credential.
2. Choose managed OAuth if offered.
3. Select Sign in with Google.
4. Grant access to the account that owns or can edit the spreadsheet.
5. Save and test the credential.

Self-hosted n8n

Self-hosted users must configure a custom OAuth client:

1. In n8n, create a Google Sheets OAuth2 API credential and copy the displayed OAuth Redirect URL.
2. In Google Cloud Console, create or select a project.
3. Open APIs & Services → Library.
4. Enable Google Sheets API.
5. Enable Google Drive API; n8n’s Google Sheets integration requires both.
6. Configure the Google Auth Platform/consent screen.
7. Choose Internal for one Workspace organization or External for normal Google accounts.
8. If the app is External and in Testing mode, add the Google account used by n8n as a test user.
9. Create an OAuth client of type Web application.
10. Add the exact redirect URL copied from the n8n credential under Authorized redirect URIs.
11. For a public self-hosted domain, add that domain where Google requests authorized domains.
12. Copy the Client ID and Client Secret into n8n.
13. Save, choose Sign in with Google, approve access, and test the credential.

The redirect URL is derived from the n8n editor/public URL. If the domain changes, update the n8n environment and Google client before reconnecting.

Minimum access rule

Use a dedicated Google account or dedicated spreadsheet where practical. Give the connected account edit access only to the assets this automation needs.

LLM provider

Use one n8n-compatible chat-model provider. The downloaded workflow is prewired to NVIDIA Nemotron, but you can replace only its model subnode with OpenAI, Anthropic, OpenRouter, Gemini, or another provider supported by your n8n installation. Do not connect multiple live models to the analysis node.

Option A — included NVIDIA wiring

Generate the key

1. Sign in at NVIDIA build.
2. Open the Nemotron model catalogue entry.
3. Choose Get API Key.
4. Copy the key into a password manager.

Create the n8n credential

1. In n8n, create an NVIDIA Nemotron API credential.
2. Keep the cloud Base URL as https://integrate.api.nvidia.com/v1.
3. Paste the NVIDIA API key.
4. Save and test.
5. Select this credential in NVIDIA Nemotron Chat Model.

The included model is:

nvidia/llama-3.3-nemotron-super-49b-v1.5

Reference settings are temperature 0.2, maximum output 900 tokens, request timeout 120000 ms, and two provider retries. Keep structured JSON output enabled because downstream validation expects named fields.

Option B — another chat-model provider

1. Create the provider credential in n8n using the provider's official credential type or a compatible community node you have reviewed.
2. In workflow 01, disconnect NVIDIA Nemotron Chat Model from the AI analysis node.
3. Add the chosen provider's chat-model subnode and connect it to the same model input.
4. Select the provider credential and a model that supports the required structured response.
5. Keep the existing analysis prompt, structured schema, low-temperature baseline, and downstream field names.
6. Leave only one chat-model subnode connected.
7. Rename the NVIDIA-labelled failure nodes if desired, then run the model success, invalid-output, timeout, and exhausted-retry tests.

Model names, endpoints, pricing, rate limits, and data-processing terms vary by provider. Check the provider's current documentation before production use.

Key handling

• Do not add the key to Docker Compose unless you intentionally manage secrets there.
• Never publish execution input that contains a raw key.
• Rotate the key if it appears in a screenshot, browser console, or shared export.

SMTP

Collect provider settings

Ask the email provider for:

• SMTP hostname;
• port;
• username, usually the mailbox address;
• password or app password;
• required encryption method;
• a permitted From address and sender name.

Typical secure combinations are port 465 with implicit SSL/TLS enabled, or port 587 with SSL/TLS disabled so the connection upgrades through STARTTLS. Use the provider’s instructions as the authority.

Create the n8n credential

1. In n8n, create an SMTP credential for the Send Email node.
2. Enter the user, password/app password, host, and port.
3. Set SSL/TLS to match the provider.
4. Leave Disable STARTTLS off unless the provider explicitly requires it.
5. Leave Client Host Name empty unless the mail administrator provides an FQDN.
6. Save and test.
7. Select the credential in Send via SMTP.
8. Change the node’s From field to <SENDER_NAME> <<VERIFIED_FROM_ADDRESS>>.

Configure SPF, DKIM, and DMARC at the sending domain where available. They are outside n8n but materially affect delivery and spoofing protection.

Gmail — optional alternative

The Gmail node is intentionally disconnected. Use it only if the installer prefers Google OAuth over SMTP.

1. Create a Gmail OAuth2 credential.
2. For self-hosted n8n, enable Gmail API in Google Cloud and configure the OAuth client as described above.
3. Select the credential in Send via Gmail.
4. Disconnect both links touching Send via SMTP.
5. Connect Prepare Email Payload → Send via Gmail → Capture Email Delivery.
6. Confirm To, Subject, HTML/text body, sender name, and attribution settings.
7. Leave SMTP disconnected beside the Gmail node.
8. Repeat Approve and Edit reply tests.

Do not connect both provider nodes at once; doing so can send duplicate emails.

Credential completion checklist

• Telegram credential tests successfully and the owner has pressed Start.
• Google Sheets credential can list/read the target spreadsheet.
• the chosen LLM credential can execute its connected chat model;
• SMTP credential sends to a tester-owned address.
• No credential value is present in any exported JSON or public screenshot.

Official references

• n8n: Telegram credentials
• Telegram Bot API
• n8n: Google OAuth2 single service
• n8n: NVIDIA Nemotron credentials
• NVIDIA: included Nemotron model
• n8n: AI model integrations
• n8n: Send Email/SMTP credentials

Form & Sheets

Create the Google Form

Create a blank Google Form with:

• Title: AI Automation Enquiry
• Description: Tell us where manual work is slowing your business down. AI will organise and prioritise your enquiry, and a human will review any consequential follow-up.
• Confirmation message: Thanks — your enquiry has been received and will be reviewed.
• Collect email addresses: Off; the form includes its own required email field.
• Limit to one response: Off if external prospects must respond without signing in.

Publish the form to the audience you intend to serve. “Anyone with the link” is suitable for a public demo, but it also means the form is public—do not request secrets or highly sensitive data.

Use the demonstration questions—or your own

The ten questions below are the demonstration blueprint used by 03-google-form-builder.json. You do not have to use the same visible question wording. If you use this exact blueprint, preserve capitalization, punctuation, and spacing so the included mapper works without changes.

Do not add another automatic email collection column unless you also update Map Google Form Response; duplicate email columns can cause ambiguous mapping.

Map custom form fields

Google Forms writes each question title into row 1 of the response sheet. Workflow 01 reads those column titles in Map Google Form Response and converts them into these canonical workflow fields:

full_name, business_email, company_name, business_type, service_needed, monthly_lead_volume, budget_range, timeline, challenge, and contact_consent.

To use your own question titles:

1. Submit one response through your custom form so its real column headers appear in the response sheet.
2. Open Map Google Form Response in workflow 01.
3. Add each of your column titles to the matching pick(...) call. Put the exact sheet header in quotes; matching is case-sensitive.
4. Keep the canonical property names on the left unchanged unless you are also updating validation, scoring, AI input, reporting, and Telegram/email expressions downstream.
5. Execute only the mapper with a real test row and inspect its output before publishing.

For example, a form that asks Contact person, Work email, and Organisation can use:

full_name: pick('Contact person', 'Full name', 'full_name'),
business_email: pick('Work email', 'Business email', 'business_email'),
company_name: pick('Organisation', 'Company name', 'company_name'),

Repeat that pattern for all ten canonical fields. The first non-empty alias wins, so you may support several forms by listing each known header in the same pick(...) call. For substantially different forms, a separate mapper node per form is clearer and safer.

All ten canonical fields are required by Validate, Normalize & Pre-Score in the included workflow. If your form intentionally omits one, you must either map a justified default or update the validator’s required array and review every downstream scoring, AI, report, Telegram, and email expression that uses that field. Do not invent placeholder values merely to bypass validation.

Link responses to Google Sheets

1. Open the form’s Responses tab.
2. Choose Link to Sheets.
3. Create a new spreadsheet, suggested name AI Automation Enquiry — Responses.
4. Submit one test response so Google creates and populates Form Responses 1.
5. Verify row 1 contains Timestamp followed by the ten exact question labels.

The spreadsheet URL has this shape:

https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=<SHEET_ID>

Copy:

• <SPREADSHEET_ID> from between /d/ and /edit;
• <RESPONSE_SHEET_ID> from the gid value while Form Responses 1 is selected.

Create the Workflow Report tab

Add a second tab named Workflow Report. Paste this tab-separated header row into cell A1:

created_at	lead_id	submitted_at	full_name	business_email	company_name	business_type	service_needed	source	rule_score	rule_tier	ai_fit_score	ai_lead_tier	ai_urgency_score	ai_confidence	summary	pain_points	review_reason	reply_subject	proposed_reply	final_reply	approval_action	approval_status	telegram_context	email_delivery	last_updated_at

Then:

1. Freeze row 1.
2. Turn on a filter.
3. Keep lead_id unique; the workflows upsert/update by this value.
4. Select the report tab and copy its gid as <REPORT_SHEET_ID>.
5. Do not rename report columns without updating all mapping expressions.

Configure the Google Sheets nodes

Select the Google credential and replace document/sheet IDs on these nodes.

Workflow 01

• Read Google Form Response Sheet → response sheet.
• Upsert Workflow Report → report sheet.
• Save Review Message Context → report sheet.

Workflow 02

• Find Report by Lead ID → report sheet.
• Find Report by Edit Prompt → report sheet.
• Save Awaiting Edit State → report sheet.
• Update Final Workflow Report → report sheet.

Use the same <SPREADSHEET_ID> for every node. Use <RESPONSE_SHEET_ID> only for the read node and <REPORT_SHEET_ID> for all report nodes.

How polling and deduplication work

Poll Google Form Responses runs every minute. Read Google Form Response Sheet reads rows, Only New Google Form Responses compares timestamped row fingerprints with workflow static data, and only unseen rows continue. Fingerprints are retained for 90 days with a bounded recent set.

Expected behavior:

• a response may take slightly more than one minute to appear;
• republishing the workflow does not normally replay remembered rows;
• clearing n8n data or replacing the workflow can clear static fingerprints and allow old rows to re-enter;
• editing an old response row can change its fingerprint and cause reprocessing.

For a clean production launch, test with temporary rows, delete those response rows, and confirm the workflow is not processing historical submissions before publishing.

Native n8n form option

Workflow 01 also includes Lead Intake Form with canonical field keys. It enters the same validation path without Google polling. After publishing, copy its production form URL from the trigger node. If the form is public, the self-hosted n8n instance must remain reachable through HTTPS.

Using more than one form

Each form schema needs its own adapter before the shared validation node. Do not connect a differently shaped form directly and hope missing fields will be inferred.

For every additional form:

1. Add its trigger/read branch.
2. Add a dedicated mapper that outputs the ten canonical fields.
3. Provide explicit empty/default values only for fields the business has intentionally made optional.
4. Set a distinct source value.
5. Validate the mapped object before merging into Validate, Normalize & Pre-Score.
6. Test that missing required fields stop safely rather than producing a misleading AI result.

Optional Form builder warning

03-google-form-builder.json is included in the ZIP and as an individual download. It is a setup utility, not a production trigger. Replace FORM_ID, connect a Google OAuth credential with Forms access, and inspect its request body before running it. It deletes the target form’s existing questions before rebuilding the demonstration blueprint. Use it only with a new form or a form you are willing to overwrite, and keep it unpublished after setup.

Configure

Required replacement table

Replace every demo-specific value before publishing.

Workflow 00 — Error handler

Open 00 - Production Error Handler (Telegram):

1. Workflow Error Trigger: no credential required.
2. Format Safe Error Alert: retain the sanitizer; customize only the business-facing prefix if desired.
3. Send Error Alert to Owner: select the Telegram credential and enter <OWNER_CHAT_ID>.
4. Save and publish this workflow first.

The handler should report workflow name, execution ID/URL when available, node, time, and a shortened error message. It should not send full input data, authorization headers, credential objects, or stack dumps to Telegram.

Workflow 01 — Intake and analysis

Intake triggers

• Manual Test Trigger and Sample High-Intent Lead are retained for safe setup testing.
• Lead Intake Form is the native form option.
• Poll Google Form Responses runs every minute.

Keep all three connected if you want all sources. If removing a source, remove or disable its whole branch without changing the shared validation path.

Google response reader

On Read Google Form Response Sheet:

• choose the Google Sheets credential;
• set document to <SPREADSHEET_ID>;
• set sheet to <RESPONSE_SHEET_ID> / Form Responses 1;
• leave the mapper’s expected labels unchanged unless the Form changed.

Validation and scoring

Validate, Normalize & Pre-Score:

• trims and normalizes strings;
• validates required fields and business email shape;
• produces a stable lead_id;
• calculates rule_score and rule_tier;
• prevents invalid input from reaching the LLM.

Review the scoring weights before using the tiers for sales operations. They are portfolio defaults, not universal business truth.

LLM model

The included workflow uses NVIDIA Nemotron Chat Model. On that node:

• select the NVIDIA credential;
• choose nvidia/llama-3.3-nemotron-super-49b-v1.5;
• retain structured JSON response mode;
• use temperature 0.2, max tokens 900, timeout 120000 ms, and two retries as the baseline.

The downstream logic expects structured fields for fit score, lead tier, urgency, confidence, summary, pain points, recommended action, reply subject, reply draft, and review reason. If you change the prompt or model, test malformed, missing, and out-of-range values.

To use OpenAI, Anthropic, OpenRouter, Gemini, or another supported provider, disconnect the NVIDIA model subnode, add the provider's chat-model subnode, connect it to the same AI analysis node, and preserve the structured-output requirements and downstream field names. Keep only one live model connection.

LLM failure path

Prepare NVIDIA Failure Alert and Notify NVIDIA Failure (Telegram) are the included provider-specific names for the exhausted-retry path. Configure the Telegram credential and <OWNER_CHAT_ID>. If you replace the provider, rename these nodes for clarity and verify that the new model's errors still reach this path. The failure is recorded without continuously retrying the same Google Form row.

Mandatory review policy

Keep Apply Safety & Approval Rules configured so every valid lead is marked for review. Risk conditions—HOT tier, no consent, low confidence, large score disagreement, or explicit model concern—are included as reasons, but none bypass Telegram.

Human Review Required? remains part of the readable design; its production route must send every valid lead to the review/report path.

Report nodes

Configure Upsert Workflow Report and Save Review Message Context with the Google credential, <SPREADSHEET_ID>, and <REPORT_SHEET_ID>. The first creates/updates the lead row; the second saves the Telegram message identifiers after delivery.

Telegram review

On Send Telegram Review Message:

• select the Telegram credential;
• set chat to <OWNER_CHAT_ID>;
• retain HTML parse mode;
• retain Approve, Edit reply, and Reject callback buttons;
• retain dynamic-value escaping;
• retain retry-on-fail settings.

Do not use Telegram’s “send and wait for approval” operation here. This design sends a normal message and finishes; the dispatcher receives later updates.

Workflow settings

• Error workflow: 00 - Production Error Handler (Telegram).
• Timeout: 600 seconds.
• Timezone: <TIMEZONE>.
• Save successful and failed production executions during initial operation.

Workflow 02 — Approval dispatcher

Telegram trigger

On Telegram Owner Response:

• select the same bot credential;
• receive callback_query and message updates;
• restrict Chat IDs to <OWNER_CHAT_ID>;
• restrict User IDs to <OWNER_USER_ID>;
• confirm no other active Telegram Trigger uses this bot.

The workflow recognizes a button callback or a direct reply to the edit prompt. Unrelated chat messages exit without changing a report row.

Callback validation

Do not remove the report lookup, 24-hour age check, pending-state check, or review-message locking. These nodes prevent repeated button presses, stale callbacks, and already-completed leads from sending email.

Edit reply path

Request Edited Reply sends a force-reply prompt. Save Awaiting Edit State stores the prompt’s Telegram identifiers. The owner must use Telegram’s Reply action on that exact prompt; a new standalone message is intentionally ignored.

The edited Telegram text becomes the final email body. The proposed subject remains unless you extend the edit protocol to collect a subject explicitly.

SMTP path

On Send via SMTP:

• select the SMTP credential;
• set From to <SENDER_NAME> <<VERIFIED_FROM_ADDRESS>>;
• keep To, Subject, and Body as expressions from Prepare Email Payload;
• retain three retry attempts;
• route errors onward so delivery failure is recorded.

The only connected email chain should be:

Prepare Email Payload → Send via SMTP → Capture Email Delivery

Leave Send via Gmail disconnected beside it with Email Provider Switch Note. To use Gmail, swap the node manually as described in Credentials.

Final report and owner status

Configure Find Report by Lead ID, Find Report by Edit Prompt, Save Awaiting Edit State, and Update Final Workflow Report with the same spreadsheet/report tab. Send Owner Status must use the Telegram credential and owner chat.

Expected terminal statuses:

• Approve: APPROVED / COMPLETED when SMTP succeeds.
• Edit reply: EDITED / COMPLETED when SMTP succeeds.
• Reject: REJECTED with no email delivery.
• Provider failure: action retained with failed delivery details for investigation.

Workflow settings

• Error workflow: 00 - Production Error Handler (Telegram).
• Timeout: 300 seconds.
• Timezone: <TIMEZONE>.

Final visual inspection

Before testing, zoom out and confirm:

• no missing-credential triangles;
• one connected email provider only;
• Gmail is visibly disconnected;
• both main workflows reference the production error handler;
• every Google node points to the adopter’s spreadsheet;
• no personal demo ID remains in a Telegram or Google node.

Test

Use only test leads and email addresses you own or have permission to contact. Keep the workflows unpublished until the manual and node-level checks pass.

Test 1 — Credential checks

Confirm separately:

• Telegram credential connects and the bot can send a plain message to <OWNER_CHAT_ID>.
• Google Sheets credential can read Form Responses 1 and write a disposable row to a test tab.
• the chosen LLM credential returns a response from the configured model;
• SMTP credential sends a plain message to a tester-owned mailbox.

Delete disposable test data before continuing.

Test 2 — Manual intake path

1. Open workflow 01.
2. Select Manual Test Trigger.
3. Choose Execute workflow.
4. Follow execution data through Sample High-Intent Lead.
5. Confirm validation outputs a lead_id, valid email, score, and tier.
6. Confirm the connected LLM returns the expected structured fields.
7. Confirm one row appears in Workflow Report with source = MANUAL_TEST and a pending review status.
8. Confirm Telegram receives one review message with three buttons.
9. Do not press a button yet.

Expected: workflow 01 finishes. It should not stay waiting for Telegram.

Test 3 — Parallel lead behavior

While Test 2’s lead is still pending:

1. Run the manual trigger again or submit a different native-form test.
2. Confirm a second workflow 01 execution starts and finishes independently.
3. Confirm it creates a different lead_id, a second report row, and a second Telegram review message.

Expected: the first pending lead does not block or overwrite the second.

Test 4 — Reject

1. Press Reject on one test lead.
2. Confirm workflow 02 executes.
3. Confirm Telegram acknowledges/removes the buttons and sends an owner status.
4. Confirm the report row records rejection and a final timestamp.
5. Confirm the tester mailbox receives no email.
6. Press the old button again if still visible.

Expected: the second action is ignored/rejected and no email is sent.

Test 5 — Approve

1. Create a lead whose business email is a tester-owned mailbox.
2. Wait for its Telegram review.
3. Check the proposed subject and reply for safe content.
4. Press Approve.
5. Confirm one workflow 02 execution.
6. Confirm exactly one email arrives with the proposed subject/body.
7. Confirm the report records APPROVED, completion, final reply, provider result, and timestamp.
8. Confirm Telegram sends an owner completion status.

Expected: one email only. If both SMTP and Gmail fire, stop and correct provider wiring.

Test 6 — Edit reply

1. Create another tester-owned lead.
2. Press Edit reply.
3. Confirm Telegram sends a force-reply prompt containing the proposed reply.
4. Use Telegram’s Reply action on that exact prompt.
5. Modify the body, then send it.
6. Confirm workflow 02 matches the reply to the correct lead_id.
7. Confirm the edited body—not the original draft—arrives by email.
8. Confirm the report records EDITED, the final body, completion, delivery result, and timestamps.

Also send an unrelated standalone bot message. Expected: it must not send an email or alter a lead row.

Test 7 — Google Form path

1. Publish workflow 01 only after the dispatcher and error handler are ready.
2. Submit the Google Form with unique test values.
3. Wait at least one polling interval.
4. Confirm one workflow 01 execution and source = GOOGLE_FORM.
5. Confirm the exact form values appear in the report and Telegram.
6. Confirm only one report row is created over the next two polling intervals.
7. Complete Reject for this test.

Expected: a delayed but single processing event. If it repeats, inspect fingerprints and whether the response row is being edited.

Test 8 — Native n8n form

1. Open the production form URL from Lead Intake Form.
2. Submit all fields with a tester-owned email.
3. Confirm source = N8N_FORM.
4. Complete Approve or Edit reply.
5. Confirm the same reporting and delivery behavior as Google Form.

Test 9 — Invalid input

Test at least:

• malformed email;
• missing required value through a deliberately modified sample;
• bottleneck text shorter than required;
• contact consent No.

Expected: malformed/missing required input stops before the LLM. Consent No may still be analysed and reviewed, but the owner should reject unless there is another lawful basis and the business’s policy allows contact.

Test 10 — LLM provider failure

In a duplicate/unpublished workflow, temporarily choose an invalid model or disconnected test credential.

Expected:

• retries occur;
• the owner receives a concise provider failure alert (the included node names mention NVIDIA);
• no approval email is possible;
• the Google Form row does not enter an endless retry loop.

Restore the production model and credential after the test.

Test 11 — Error workflow

Use the included 05-error-handler-smoke-test.json or a duplicate workflow with a controlled Stop and Error node.

Expected: workflow 00 runs and sends the owner a sanitized alert with enough information to find the failed execution, but without input payloads or secrets.

Test 12 — Expired/stale action

For a non-production test row, change its pending timestamp to more than 24 hours ago and press its button.

Expected: the dispatcher refuses the action and sends no email.

Acceptance matrix

Evidence to capture for the website demo

• redacted workflow canvas screenshots;
• a sample Google Form using fictional data;
• a Telegram review, edit prompt, and completion message with names/emails blurred;
• a report row with identifiers anonymized;
• an email delivered to a tester-owned address;
• execution timestamps and IDs only if they do not reveal private instance URLs.

Operate & Fix

Daily operating loop

1. Watch Telegram for new review cards and production alerts.
2. Review the original enquiry, consent, scores, summary, and draft.
3. Choose Approve, Edit reply, or Reject within 24 hours.
4. Confirm Telegram reports the final result.
5. Review failed n8n executions and report rows with incomplete delivery.

Do not treat the AI score as permission to contact a lead. The owner remains responsible for consent, accuracy, tone, and business policy.

Execution retention and privacy

The reference deployment retains n8n execution history and response fingerprints for 90 days. Adapt the period to local privacy obligations and business needs. Execution data can contain names, email addresses, enquiry text, AI output, and delivery metadata.

• limit access to n8n and the report spreadsheet;
• avoid sharing raw executions in support posts;
• redact personal data in screenshots;
• remove stale lead data under the business’s retention policy;
• do not record SMTP passwords, API keys, or bot tokens in report rows.

Backups

Back up both parts:

1. n8n persistent data volume/database and encryption key;
2. Google Form/Sheet assets or an export of the report.

The project reference includes an infrastructure backup script. Test restoration periodically. A backup is incomplete if the database is copied without the encryption key needed to decrypt credentials.

Before an n8n upgrade:

• export the three workflows;
• back up persistent data;
• note the current n8n image version;
• test the upgrade with duplicates or a staging instance;
• repeat the acceptance matrix.

Telegram: “chat not found”

Likely causes:

• the owner has not pressed Start in the bot chat;
• the Chat ID is wrong;
• a group/channel ID was used without adding the bot;
• the selected credential belongs to a different bot.

Fix: press Start, rerun a temporary trigger test, copy message.chat.id, and confirm every send node uses the same credential and ID.

Telegram Trigger does not activate

Check:

• n8n has a stable public HTTPS URL;
• WEBHOOK_URL uses that URL and ends with /;
• N8N_PROXY_HOPS=1 when one reverse proxy is used;
• forwarded host/protocol headers reach n8n;
• the dispatcher is published;
• no other active Telegram Trigger is using the same bot token.

If a tunnel URL changed, update n8n’s public URL, restart it, reopen the trigger, and republish so Telegram receives the new webhook.

Telegram “Bad Request: can’t parse entities”

The review uses HTML parse mode. Dynamic text must be escaped for &, <, and >. Do not switch to Markdown without updating the escaping logic; source names and model text can contain characters Telegram treats as markup.

Buttons open a browser instead of continuing in chat

Confirm Send Telegram Review Message sends normal inline callback buttons and the dispatcher receives callback_query. Do not use an n8n “send and wait for approval” operation; that mode may use browser-based resume URLs.

Edit reply is ignored

The owner must reply to the exact force-reply prompt. Check that:

• Save Awaiting Edit State stored the prompt chat/message ID;
• the incoming Telegram message has reply_to_message.message_id;
• Find Report by Edit Prompt finds one pending row;
• the reply arrived within the 24-hour window;
• the sender matches <OWNER_USER_ID>.

Google OAuth redirect_uri_mismatch

Copy the redirect URL shown inside the n8n credential and paste it exactly into the Google OAuth web client. Check scheme, domain, path, trailing slash, and whether the n8n public URL changed. For self-hosted n8n, the editor must be available at the domain used during OAuth.

Google says the app is unverified or access is denied

For an External OAuth app in Testing mode, add the connected Google account as a test user. Ensure Google Sheets API and Google Drive API are enabled in the same project as the OAuth client.

Google Form submission is not processed

Check:

• workflow 01 is published;
• the schedule trigger is enabled;
• the Google account can open the linked spreadsheet;
• document and response sheet IDs are correct;
• row 1 question labels match exactly;
• at least one minute has passed;
• the execution list does not show a mapping or OAuth error.

Google Form submission repeats

Possible causes:

• n8n persistent data or workflow static data was cleared;
• the workflow was re-imported as a new copy;
• an old response row was edited;
• multiple published intake workflows poll the same response sheet.

Pause duplicates, inspect lead_id values, and remove duplicate report rows only after confirming which execution is authoritative.

A second form has missing fields

Create a dedicated mapper for that form. The shared validator expects canonical fields; missing required values should stop, while silent fallbacks can corrupt scoring and email content. Keep one adapter per schema and test it independently.

LLM timeout or provider error

The reference request timeout is 120 seconds with retries. Check:

• credential test and remaining provider access/quota;
• selected model name;
• provider Base URL, if the credential requires one (https://integrate.api.nvidia.com/v1 for the included hosted NVIDIA setup);
• internet/DNS access from the n8n container;
• response size and max token setting;
• the controlled failure alert execution.

Do not increase retries indefinitely for a one-minute poller. Extended retry storms can multiply cost and delay processing.

LLM returns invalid JSON

Keep structured response mode and the downstream schema validator. Review the raw model output in a redacted execution, confirm the prompt still requests only the schema, and test the model change in a duplicate workflow. Never let an unvalidated draft enter the email payload.

SMTP authentication fails

Verify username, app password, host, port, encryption mode, and whether the provider allows SMTP. Common secure patterns are 465 with SSL/TLS on or 587 with SSL/TLS off and STARTTLS allowed. Some providers reject the normal account password and require an app password.

SMTP succeeds but mail is missing

Check spam/quarantine, recipient address, provider logs, From-address authorization, SPF, DKIM, and DMARC. A successful SMTP handoff does not guarantee inbox placement.

Duplicate email is sent

Immediately unpublish workflow 02 and inspect provider wiring. Only one of Send via SMTP or Send via Gmail may be connected. Also check for duplicate dispatcher workflows or repeated report transitions.

Report update fails

Confirm the Workflow Report headers are exact, lead_id exists and is unique, the correct sheet ID is selected, and the Google account has edit access. Do not sort/move data in a way that deletes headers or changes names.

Owner receives no production error alert

Verify the failed workflow selects 00 - Production Error Handler (Telegram) in Settings, workflow 00 is published, the bot has been started, and the error handler’s Telegram node has the correct credential/chat ID. Trigger the smoke test after any deployment change.

When to redesign the state layer

Move from Google Sheets to PostgreSQL or another transactional store when using multiple workers, processing high concurrent volume, requiring strict audit constraints, or observing update collisions. Preserve the state machine: pending → awaiting edit/approved/rejected → completed/failed.

Customize

Make one change at a time in duplicated, unpublished workflows and repeat the relevant tests.

Change the form

If a Google Form question title changes, update Map Google Form Response to use the new response-sheet header. If a new field is required:

1. add it to every intake source;
2. output it from every source adapter;
3. validate and normalize it;
4. decide whether the LLM may receive it;
5. add a report column if it must be retained;
6. escape it before Telegram HTML;
7. test missing and malicious values.

Add another intake source

Examples include Typeform, Tally, Facebook Lead Ads, a CRM webhook, or another Google Form. End every source branch with the same canonical object:

{
  "full_name": "",
  "business_email": "",
  "company_name": "",
  "business_type": "",
  "service_needed": "",
  "monthly_lead_volume": "",
  "budget_range": "",
  "timeline": "",
  "challenge": "",
  "contact_consent": "",
  "source": "YOUR_SOURCE"
}

Never connect a foreign schema directly to the shared validator.

Change scoring

The deterministic score is a transparent pre-score; the AI score is a model assessment. Before changing either:

• write down what each factor means for the business;
• keep scores bounded from 0 to 100;
• preserve low-confidence and disagreement flags;
• keep mandatory Telegram review unless the business accepts a different risk policy;
• test edge cases around every tier boundary.

Change the LLM

You may use NVIDIA, OpenAI, Anthropic, OpenRouter, Gemini, or another n8n-compatible chat model, but downstream nodes require structured output. Replace only the model subnode and preserve or remap:

• fit score and tier;
• urgency score;
• confidence;
• summary;
• pain points;
• recommended next action;
• reply subject;
• reply draft;
• review reason.

Run schema failure, timeout, and prompt-injection tests. Treat enquiry text as untrusted data; it must not override system instructions or request secrets.

Change the review channel

Slack, Microsoft Teams, WhatsApp Business Cloud, or email can replace Telegram, but the interaction model must still provide:

• authenticated owner identity;
• lead-specific action token/ID;
• Approve/Edit/Reject states;
• a reliable way to associate edited text with one lead;
• expiration and duplicate-action protection;
• an independent dispatcher execution.

Do not simply replace the Telegram send node; the trigger, state fields, callback parsing, and report context must also change.

Switch SMTP to Gmail

Use the disconnected Gmail node already on the dispatcher canvas:

1. configure Gmail OAuth;
2. disconnect SMTP on both sides;
3. connect Gmail in the same position;
4. keep SMTP parked and unconnected;
5. verify payload expressions and sender settings;
6. run Approve and Edit reply tests.

There is intentionally no runtime provider question or IF node.

Let the owner edit the subject

The current Edit reply changes the body only. A safe subject-edit extension can use a two-step Telegram state:

1. ask for the subject and store AWAITING_EDIT_SUBJECT;
2. ask for the body and store AWAITING_EDIT_BODY;
3. validate length and remove CR/LF characters from the subject;
4. send only after both values are present and the owner confirms.

Do not parse subject and body from an ambiguous free-form message without validation.

Add reminders and expiry

Add a separate scheduled workflow that queries pending rows:

• remind the owner after a chosen interval;
• mark rows expired after 24 hours;
• remove or invalidate old buttons if possible;
• never auto-send because a reminder timed out.

Move reporting to a database

For PostgreSQL, create a unique constraint on lead_id and use transactional state changes. Suggested columns mirror the 26 report headers plus version and lock timestamps. Only transition a row when its current status matches the expected state.

Add CRM handoff

After a successful email or rejection, create/update the CRM record using lead_id as the external key. Store the CRM record ID in a new report/database field. Route CRM failure to error handling without resending the lead email.

Brand the messages

Customize Telegram headings, email sender name, subject style, signature, native form title, and confirmation copy. Preserve:

• HTML escaping in Telegram;
• business-email validation;
• consent visibility;
• explicit owner action;
• delivery result capture;
• secret-free error messages.

Production hardening roadmap

• stable named HTTPS tunnel or reverse proxy;
• automated database and encryption-key backups;
• stale-approval reminders and expiry sweep;
• PostgreSQL state store for multi-worker deployments;
• rate limiting and abuse controls on public forms;
• monitoring beyond Telegram, such as uptime and centralized logs;
• formal privacy notice, retention schedule, and data-subject process;
• release tests whenever n8n, the LLM, or an email provider changes.