Integration
The spreadsheet everyone already updates
A Google Sheets integration lets a Telegram bot read configuration and write records into a sheet your team already maintains. It is the right first integration for many small operations and the wrong long-term one — the ceiling is concurrent writes, and it arrives sooner than people expect.
Google Sheets integration: auth, limits and availability
- Auth model
- OAuth 2.0
- Quota
- Per-project and per-user read and write quotas, measured per minute
- GCC availability
- No regional restriction
- Data flow
- 5 hops, worker-mediated
As of 2025-10-01, Telegram Bot API 13.4
Why this integration exists
A remarkable number of GCC businesses run on a spreadsheet, and treating that as a failing misreads the situation. The sheet works because everyone can see it, nobody needs training, and changing it requires no ticket. A bot that demands a proper database before it can do anything useful is a bot that does not get built.
So Sheets is often the correct integration for a first version. The bot reads its menu, its price list or its rota from a sheet the manager already edits, and writes orders or leads into another tab. Nobody learns a new system and the operational reality — that somebody adjusts prices on a Thursday afternoon — is preserved rather than fought.
The ceiling is real and worth naming in advance. The Sheets API is not a database: concurrent appends can interleave, there is no transaction, and read-modify-write across a range is a race. A bot writing a handful of rows an hour is fine. A bot writing several rows a second during a lunchtime rush will produce a sheet with overwritten or interleaved rows, and the symptom is missing orders rather than an error. Knowing where that line is means moving deliberately before it is crossed rather than after an incident.
How the data actually moves
A service account with the sheet shared to its email address, which is simpler and considerably more durable than per-user OAuth — the access belongs to the integration rather than to whoever authorised it. The service account key is a Worker secret, and the account is granted access to specific sheets rather than to a whole Drive.
Auth model: OAuth 2.0
Their limits, and what they mean for you
The Sheets API enforces per-project and per-user read and write quotas measured per minute.
Bursty writes hit the per-minute limit before the daily one. Appends are queued and batched rather than issued per event, which also reduces the interleaving problem.
There are no transactions, and concurrent appends to the same range can interleave.
Two writes arriving together can produce a row containing fields from both. This is the hard ceiling on Sheets as a write target and it appears as corrupted rows rather than as an error.
A spreadsheet has a hard cell limit, in the millions across all sheets.
A high-volume log will reach it eventually. Rotation or archiving is planned rather than discovered when writes start failing.
Values written as strings can be silently reinterpreted by the sheet's own formatting.
Phone numbers lose leading zeros and order references become dates. Formats are set explicitly on the target columns, since the default behaviour is confidently wrong.
How it fails, and what happens when it does
Two orders are appended at the same moment and one row is corrupted.
Appends are serialised through a queue rather than issued concurrently. This is the failure that makes people distrust the whole integration, and it is entirely avoidable.
Someone sorts or deletes rows while the bot is writing.
Row indices shift under the bot. Writes append rather than target positions, and reads match on a key column rather than on a row number.
A manager renames a tab.
Reads fail immediately and loudly, which is the better outcome — the alternative is a bot reading the wrong tab and serving yesterday's prices confidently.
The sheet is un-shared from the service account.
All operations fail at once. The Worker checks access on startup so this appears as a deploy-time error rather than as a silent stop.
Availability in the UAE and the wider GCC
Global
No regional restriction. A Google account or Workspace domain is all that is required.
Small operations
The intended case, and where this integration earns its place. It preserves how the team already works instead of replacing it.
High write volume
Not suitable. Beyond a few writes per second the interleaving problem produces data loss, and the honest advice is to move the write target to a database and keep the sheet as a view.
Regulated record keeping
A spreadsheet anyone can edit is a poor audit trail. Where records must be tamper-evident, the database is the record and the sheet is a convenience.
When not to use this integration
- You are writing more than a few rows per second. Interleaving produces corrupted rows and the symptom is missing orders rather than an error.
- The sheet needs to be the system of record for anything financial. Anyone with access can edit history, which is not an audit trail.
- Multiple people edit the same range while the bot writes. Row indices move underneath it and reads start returning the wrong thing.
- You already have a database and are adding a sheet for convenience. Then the sheet should be a read-only projection, not a second writer.
What it runs on
| Component | Version | Why |
|---|---|---|
| Cloudflare Workers | current | Service account auth, queued appends and batched reads. |
| Cloudflare D1 | current | The actual source of truth, projected into the sheet. |
| Cloudflare KV | current | Cached configuration read from the sheet, refreshed on a schedule. |
| Zod | 4.4 | Validation of sheet-sourced configuration, which humans edit freely. |
Questions that come up during scoping
Is a spreadsheet really an acceptable integration?
For a small operation, often yes, and dismissing it usually means the bot does not get built. The sheet works because everyone can see it and nobody needs training. The important thing is knowing where the ceiling is rather than pretending there is not one.
Where exactly is that ceiling?
Concurrent writes. There are no transactions, so two appends arriving together can interleave into one corrupted row. A few rows an hour is comfortable; several a second during a rush is not, and the symptom is missing orders rather than an error message.
Should the bot write to the sheet or to a database?
To the database, with the sheet as a projection of it. Writing to the sheet first makes the spreadsheet the system of record, which is exactly where the concurrency problems turn into data loss you cannot reconstruct.
Why do phone numbers lose their leading zeros?
The sheet reinterprets values according to column formatting, and the default behaviour is confidently wrong for identifiers. Formats are set explicitly on the target columns as part of setup.
What happens when someone sorts the sheet?
Row indices shift under the bot, which is why writes append rather than target positions and reads match on a key column rather than a row number. Assuming stable row numbers is the second most common Sheets integration bug.
Service account or per-user OAuth?
A service account with the sheet shared to its address. Access belongs to the integration rather than to whoever authorised it, so it survives the person who set it up moving on.
Related reading
For structured records with real field types and a proper API, compare against the Airtable integration.
Where the sheet is one step in a longer automation, see the Zapier integration.
The most common bot backed by a spreadsheet at first is the ordering build.
Rotas held in a sheet are a normal starting point for the dispatch build.