TELEGRAM → GOOGLE SHEETS: A SMALL CAPTURE REFERENCE
WeMAIde · 2026-10-24 · Node.js 22+ · no external packages

1. DOWNLOAD AND RUN THE OFFLINE DEMO
Save telegram-sheets-reference.mjs in a folder, then run:
node telegram-sheets-reference.mjs --demo

Expected: mode offline-synthetic; first/replay/secondRequest confirmed;
rows 2 and messages 2. Replaying the first submission creates neither another
row nor another notification. The second legitimate request is retained.
This mode does not call Telegram, Google or an AI provider and needs no keys.

2. WHAT THIS REFERENCE IMPLEMENTS
A confirmed enquiry → stored intent → one attempted Sheets append → recorded
write outcome → separate Telegram acknowledgement → recorded notification outcome.
One worker serialises processing. Stable submission identity is separate from
the chat identity, so one person can make multiple requests.

If an append response is lost, the next attempt searches by submission identity
and compares the request type, summary and chat identity. One matching row can
reconcile the write. Zero, multiple or conflicting matches require review.
A missing row immediately after a timeout is not treated as permission to append again.
An uncertain Telegram acknowledgement is not resent automatically.

3. CONNECTING YOUR OWN APPLICATION
The module exports createCapture, MemoryStore, JsonFileStore,
googleSheetsAdapter and telegramAdapter.
Import the module from your application; pass store, sheets and telegram adapters.
Call capture.process only after your conversation has shown a summary and obtained
the user's confirmation. Use a server-generated stable submission reference.
Example confirmed input (synthetic):
{ confirmed: true, submissionId: 'enquiry-demo-0042', chatId: 'synthetic-chat',
  requestType: 'Booking bot', summary: 'A synthetic enquiry' }

Live adapter configuration:
googleSheetsAdapter({accessToken, spreadsheetId, sheetName: 'Enquiries'})
telegramAdapter({botToken})
Provide short-lived Google access through your existing supported OAuth flow;
the adapter does not obtain or refresh credentials. Keep credentials in your
server's secure configuration, never in this downloadable file or a browser.
Do not log raw token-bearing Telegram URLs or request headers.

Create a dedicated test sheet with header row 1, columns A:F:
submission_id | received_at_utc | request_type | summary | chat_id | operator_status
Append uses RAW input. Do not rename, reorder or delete columns without changing
and testing the adapter. Row number is only a current location, not identity.
Give the configured identity access only to the intended spreadsheet.

For a local single-worker experiment, use JsonFileStore with an explicit file path
in a protected folder whose parent exists. It stores enquiry data, so apply your
retention and access policy. Do not share that runtime file. The default demo
uses MemoryStore and does not create it.

4. VERIFICATION AND LIMITS
Automated checks cover replays, concurrent calls in one worker, separate requests,
lost append responses, unresolved writes, changed payloads, multiple rows,
notification uncertainty and adapter request/response handling using synthetic data.
The live Telegram and Sheets endpoints were not exercised with real accounts.

This is a reference implementation, not a turnkey chatbot or a production guarantee.
It does not implement the Telegram conversation/webhook, OAuth renewal, a multi-worker
transactional store, automatic operator reconciliation, quotas/backoff or monitoring.
The file store is a single-process teaching adapter, not a database transaction or
crash-proof distributed queue. Exactly-once external delivery is not promised.

Before production: add authenticated intake, consented data collection, a durable
transactional store and worker claims, bounded retries, an operator review queue,
credential renewal, retention and monitoring. Reconcile unknown outcomes deliberately.

GUIDE AND SOURCES
https://wemaide.com/insights/telegram-bot-google-sheets-integration
https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/append
https://developers.google.com/workspace/sheets/api/reference/rest/v4/ValueInputOption
https://core.telegram.org/bots/api#sendmessage