SpreadsheetBot

2.5.2 verified Sat May 09 auth: no python

A Python library to build Telegram bots where the bot logic and data are managed via Google Spreadsheets. Version 2.5.2, actively maintained. Targets Python >= 3.11. Release cadence: irregular.

pip install spreadsheetbot

Common errors

error AttributeError: module 'spreadsheetbot' has no attribute 'Bot' ↓

cause Trying to use old import from v1.x after upgrading to v2.x.

fix

Use 'from spreadsheetbot import SpreadsheetBot' instead.

error gspread.exceptions.APIError: {'code': 403, 'message': 'The caller does not have permission'} ↓

cause Service account lacks editor access to the spreadsheet.

fix

Share the spreadsheet with the service account email with 'Editor' permissions.

error telegram.error.InvalidToken: Token is invalid ↓

cause TELEGRAM_BOT_TOKEN environment variable not set or contains invalid token.

fix

Ensure TELEGRAM_BOT_TOKEN is set correctly. Run: export TELEGRAM_BOT_TOKEN='your:token'

error KeyError: 'TELEGRAM_BOT_TOKEN' when starting bot.run() ↓

cause The environment variable is missing. SpreadsheetBot expects it to be set at runtime.

fix

Set the environment variable before running: export TELEGRAM_BOT_TOKEN='your:token'

Warnings

gotcha Do not reuse the same spreadsheet ID across multiple bot instances. The library assumes exclusive access for command registration and state management. ↓

fix Use a separate spreadsheet for each bot instance, or manage data isolation manually.

breaking Version 2.0.0 completely reworked the API. Old code using v1.x classes like 'Bot' and 'SheetManager' will not work. The main class is now 'SpreadsheetBot'. ↓

fix Upgrade code to use the new API: replace 'from spreadsheetbot import Bot' with 'from spreadsheetbot import SpreadsheetBot' and adjust method calls accordingly.

gotcha Google service account credentials must have editor access to the spreadsheet. If the bot fails to write, check spreadsheet sharing settings. ↓

fix Share the spreadsheet with the service account email (found in the JSON credentials file) with 'Editor' role.

breaking Telegram bot token must be set via environment variable TELEGRAM_BOT_TOKEN. Previously, some examples passed it directly; that no longer works. ↓

fix Set the environment variable TELEGRAM_BOT_TOKEN. Remove any direct token parameter from SpreadsheetBot constructor.

Imports

SpreadsheetBot
wrong
```
from spreadsheetbot.bot import SpreadsheetBot
```
correct
```
from spreadsheetbot import SpreadsheetBot
```
Incorrect import path from older examples; previous package structure may have used submodule.
Config
```
from spreadsheetbot import Config
```
Config class is directly available from the top-level package.

SpreadsheetHandler

wrong

from spreadsheetbot.handler import SpreadsheetHandler

correct

from spreadsheetbot import SpreadsheetHandler

SpreadsheetHandler is imported from the main package, not a submodule.

Quickstart

Minimal example to start a Telegram bot driven by a Google Spreadsheet. Requires TELEGRAM_BOT_TOKEN environment variable and a service account JSON file.

from spreadsheetbot import SpreadsheetBot
from spreadsheetbot import Config

# Configure with your Google Sheets ID and credentials
config = Config(
    spreadsheet_id='1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
    credentials_file='service_account.json'
)

# Create bot instance
bot = SpreadsheetBot(config)

# Start polling (uses Telegram bot token from environment TELEGRAM_BOT_TOKEN)
bot.run()