Overview

The Massage Booking Telegram Bot is a booking system for a massage studio (or similar service business) where clients book in Telegram and staff approve or reject requests.

The platform combines dynamic time slots, double-booking prevention, optional Google Calendar sync, automated client reminders, and a web panel for day-to-day operations.

The project targets a small team workflow: one service on a VPS, PostgreSQL as the data store, and a clear operational model without heavy messaging infrastructure.

Context

The goal was to replace manual chat-based scheduling with a structured flow that still feels natural in Telegram.

Key requirements included:

• guided booking (duration, therapist, date, time, contact details);
• dynamic slots based on working hours and session length;
• admin approval before a booking is finalized;
• staff roles and master management;
• Ukrainian and English bot UI;
• optional Google Calendar integration;
• automated client reminders;
• a web panel to review and process appointments.

Responsibilities

Responsibilities across the project included:

• application architecture and module layout;
• Telegram bot (aiogram 3) and FSM booking flow;
• PostgreSQL schema and Alembic migrations;
• slot generation and conflict detection;
• confirm/reject flows with client notifications;
• Google Calendar integration;
• APScheduler-based reminders;
• FastAPI web admin;
• Docker image, compose stack, and GitLab CI/CD deployment.

Solution

The solution is implemented as a single Python service that handles Telegram interaction, background reminders, and optionally the web admin.

Clients choose session parameters in Telegram, see available slots, and receive status updates after staff action. Admins work in Telegram or the web panel: they review pending bookings and confirm or reject them with a fresh availability check.

Availability accounts for pending and confirmed records in the database and, when configured, busy time from Google Calendar. If the external calendar is unavailable, the system continues using PostgreSQL data.

Technical Details

Stack

• Python 3.12
• aiogram 3
• PostgreSQL
• SQLAlchemy 2 (async)
• Alembic
• FastAPI
• APScheduler
• Google Calendar API
• Docker
• GitLab CI

Architecture

The project separates:

• Telegram handlers and the booking FSM;
• slot, reminder, and appointment action services;
• repositories and ORM models;
• the web admin layer;
• database schema migrations.

Shared confirm/reject logic is used in both Telegram and the web panel to keep business rules consistent.

Functionality

Implemented functionality includes:

• localized bot UI (UA/EN);
• booking with dynamic slots and conflict checks;
• owner / admin / master roles;
• appointment confirmation and rejection;
• optional Google Calendar sync;
• client reminders before visits;
• web admin for appointments, masters, and read-only clients;
• deployment via Docker and GitLab CI.

Challenges

Main challenges included:

• aligning availability between the database and an external calendar;
• safe confirmation when multiple admins act on the same slot;
• keeping business rules identical in Telegram and the web UI;
• reliable reminders without duplicate messages;
• production deployment and operations on a VPS.

Result

The project delivered:

• a complete Telegram-first booking product;
• controlled scheduling with an admin approval step;
• optional Google Calendar integration;
• automated reminders without a separate message queue;
• a web panel for operational work;
• repeatable deployment through Docker and CI/CD.

It demonstrates how bot UX, backend logic, integrations, and production deployment can be combined for a small service business.

Media

The gallery includes:

• the Telegram booking flow;
• admin confirmation workflow;
• web admin screens;
• examples of the system in production use.

Notes

• Production-oriented booking product.
• Telegram as the primary client channel.
• Web admin supports staff operations alongside the bot.