Telegram Booking Bot

A Google Apps Script–powered Telegram bot for managing studio session bookings, backed by Google Calendar and Google Sheets.

Built for CCA usage, to replace a manual booking process with an automated interactive Telegram interface.

---

What is Google Apps Script?

Google Apps Script (GAS) is a cloud-based JavaScript runtime built into the Google Workspace ecosystem. It runs entirely on Google's servers — no local environment, no build step, no deployment pipeline. Scripts are written in standard JavaScript (ES5/ES2015+) and have first-class access to Google services like Calendar, Sheets, Gmail, and Drive through built-in APIs.

Why .gs?

Source files use the .gs extension instead of .js. Functionally they are plain JavaScript; the extension is simply the convention used by the Apps Script editor and the clasp CLI tool that syncs local files with the cloud project.

Why is everything flat in src/?

Apps Script projects have a flat file namespace — all .gs files are loaded into the same global scope at runtime, regardless of what directory structure you organise them into locally. There is no import/require between files; instead, all functions and classes are globally accessible from any file. The src/ directory here is purely for local readability and version control; the structure does not carry over into the Apps Script editor.

---

Features

• Book a session — Pick a CCA group, browse an inline calendar, and select start/end times from dynamically generated time-slot buttons. Clashes are automatically blocked.
• Check a date — View all existing bookings for any day at a glance.
• Delete a booking — Users can delete only their own future bookings via an inline menu.
• Subscribe to calendar — One-tap link to add the shared Google Calendar to a user's own calendar.
• Alert channel — Optional Telegram channel notifications on new bookings and deletions.
• Whitelist mode — Optional flag to restrict booking access to approved users only.
• Kill switch — Instantly disable bookings without touching the bot logic.

---

Architecture

Telegram  ──POST──▶  Google Apps Script Web App (doPost)
                            │
                ┌───────────┴───────────┐
                ▼                       ▼
         executeCommands         executeCallback
         (text commands)         (inline button presses)
                │                       │
       ┌────────┘               ┌───────┘
       ▼                        ▼
  Google Sheets            Google Calendar
  (user database)          (bookings store)

All source files share a single global scope (standard Apps Script behaviour), which is used intentionally for shared utilities and top-level constants.

File Overview

File	Purpose
main.gs	Entry points (doPost), global constants, command routing
cmd_processing.gs	One function per bot command/callback state; orchestrates the flow
gcal_booking.gs	CalendarBooking class — creates Google Calendar events
gcal_checking.gs	CalendarCheck class — lists events for a given day
gcal_deleting.gs	CalendarDelete class — lists and removes a user's own events
inline_calendar.gs	InlineCalendar class — generates the month-grid inline keyboard
time_io.gs	TimeIn, TimeOut, TimeKeyboard classes — slot availability and time-picker keyboard
datetime.gs	Datetime class — parses and formats date/time strings
sheet_methods.gs	Google Sheets helpers — user CRUD, UUID lookup, whitelist check
methods.gs	Telegram API wrappers — sendMessage, editMessageText, etc.
utils.gs	Shared helpers — time12Convert, time24Convert

---

Callback Data Protocol

Bot state is encoded entirely in the callback_data string passed through Telegram inline button presses. No server-side session is required.

Pattern	Meaning
BK/G{n}/NAV[{page}]	Booking flow — calendar page navigation
BK/G{n}/D[{date}]/TI	Date selected — show time-in picker
BK/G{n}/D[{date}]/TI[{time}]/TO	Time-in selected — show time-out picker
BK/G{n}/D[{date}]/TI[{time}]/TO[{time}]/FN	Time-out selected — show confirmation
BK/.../CFM	Booking confirmed — write to Google Calendar
CH/NAV[{page}]	Check flow — calendar page navigation
CH/D[{date}]/CHECK	Date selected — display events
RM[{eventId}]	Delete flow — confirm prompt
RM[{eventId}]/YES	Deletion confirmed
CANCEL	Cancel any flow

---

Setup

Prerequisites: A Google account, a Telegram bot token from @BotFather, and a Google Calendar dedicated to bookings.

1. Copy the source files into a new Google Apps Script project.
2. Fill in main.gs — replace every YOUR_* placeholder with your real values (see the constants block at the top of the file).
3. Set up Google Sheets — create a spreadsheet with two sheets named Users and Groups. The bot auto-populates Users on first /start.
4. Deploy as a Web App — Deploy → New deployment → Web App, execute as yourself, accessible to anyone. Copy the URL into webAppURL in main.gs.
5. Register the webhook — run setWebHook() once from the Apps Script editor to point Telegram at your Web App URL.

---

Local Development

The repo includes a jsconfig.json that enables full Google Apps Script API autocomplete in VS Code (e.g. CalendarApp, UrlFetchApp, SpreadsheetApp), and tells VS Code's language service to treat .gs files as JavaScript.

To activate it, install the type definitions:

npm install

This installs @types/google-apps-script from package.json. No other dependencies are needed.

Commands

Command	Description
/start	Register or log in; prompts for your name on first use
/book	Start a booking
/check	View bookings on a specific date
/delete	Delete one of your own upcoming bookings
/calendar	Open the shared Google Calendar
/subscribe	Add the calendar to your own Google Calendar
/channel	Join the bookings announcement channel
/identitycrisis	Change your registered name
/help	Help link

---

Configuration Reference

All tuneable settings live at the top of main.gs:

Constant	Default	Description
globalStartTime	"0800"	Earliest bookable time (24-hour)
globalEndTime	"2300"	Latest bookable time (24-hour)
globalInterval	30	Slot size in minutes
bookingLimit	4	Max consecutive slots per booking (4 × 30 min = 2 hrs)
maxPage	1	How many months ahead users can browse
activateWhiteList	false	Restrict booking to whitelisted users
teleAlert	false	Send booking/deletion alerts to a Telegram channel
killSwitch	false	Disable all booking when true