{"id":28267,"library":"spreadsheetbot","title":"SpreadsheetBot","description":"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.","status":"active","version":"2.5.2","language":"python","source_language":"en","source_url":"https://github.com/twobrowin-study/spreadsheetbot-lib","tags":["telegram","bot","google-sheets","spreadsheet","automation"],"install":[{"cmd":"pip install spreadsheetbot","lang":"bash","label":"Latest stable"}],"dependencies":[{"reason":"Telegram Bot API client","package":"python-telegram-bot","optional":false},{"reason":"Google API authentication","package":"google-auth","optional":false},{"reason":"Google Sheets API wrapper","package":"gspread","optional":false},{"reason":"Data manipulation","package":"pandas","optional":true}],"imports":[{"note":"Incorrect import path from older examples; previous package structure may have used submodule.","wrong":"from spreadsheetbot.bot import SpreadsheetBot","symbol":"SpreadsheetBot","correct":"from spreadsheetbot import SpreadsheetBot"},{"note":"Config class is directly available from the top-level package.","symbol":"Config","correct":"from spreadsheetbot import Config"},{"note":"SpreadsheetHandler is imported from the main package, not a submodule.","wrong":"from spreadsheetbot.handler import SpreadsheetHandler","symbol":"SpreadsheetHandler","correct":"from spreadsheetbot import SpreadsheetHandler"}],"quickstart":{"code":"from spreadsheetbot import SpreadsheetBot\nfrom spreadsheetbot import Config\n\n# Configure with your Google Sheets ID and credentials\nconfig = Config(\n    spreadsheet_id='1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',\n    credentials_file='service_account.json'\n)\n\n# Create bot instance\nbot = SpreadsheetBot(config)\n\n# Start polling (uses Telegram bot token from environment TELEGRAM_BOT_TOKEN)\nbot.run()","lang":"python","description":"Minimal example to start a Telegram bot driven by a Google Spreadsheet. Requires TELEGRAM_BOT_TOKEN environment variable and a service account JSON file."},"warnings":[{"fix":"Use a separate spreadsheet for each bot instance, or manage data isolation manually.","message":"Do not reuse the same spreadsheet ID across multiple bot instances. The library assumes exclusive access for command registration and state management.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade code to use the new API: replace 'from spreadsheetbot import Bot' with 'from spreadsheetbot import SpreadsheetBot' and adjust method calls accordingly.","message":"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'.","severity":"breaking","affected_versions":"2.0.0+"},{"fix":"Share the spreadsheet with the service account email (found in the JSON credentials file) with 'Editor' role.","message":"Google service account credentials must have editor access to the spreadsheet. If the bot fails to write, check spreadsheet sharing settings.","severity":"gotcha","affected_versions":"all"},{"fix":"Set the environment variable TELEGRAM_BOT_TOKEN. Remove any direct token parameter from SpreadsheetBot constructor.","message":"Telegram bot token must be set via environment variable TELEGRAM_BOT_TOKEN. Previously, some examples passed it directly; that no longer works.","severity":"breaking","affected_versions":">=2.3.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use 'from spreadsheetbot import SpreadsheetBot' instead.","cause":"Trying to use old import from v1.x after upgrading to v2.x.","error":"AttributeError: module 'spreadsheetbot' has no attribute 'Bot'"},{"fix":"Share the spreadsheet with the service account email with 'Editor' permissions.","cause":"Service account lacks editor access to the spreadsheet.","error":"gspread.exceptions.APIError: {'code': 403, 'message': 'The caller does not have permission'}"},{"fix":"Ensure TELEGRAM_BOT_TOKEN is set correctly. Run: export TELEGRAM_BOT_TOKEN='your:token'","cause":"TELEGRAM_BOT_TOKEN environment variable not set or contains invalid token.","error":"telegram.error.InvalidToken: Token is invalid"},{"fix":"Set the environment variable before running: export TELEGRAM_BOT_TOKEN='your:token'","cause":"The environment variable is missing. SpreadsheetBot expects it to be set at runtime.","error":"KeyError: 'TELEGRAM_BOT_TOKEN' when starting bot.run()"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}