ApiSquare: Telegram-Powered Appointment Booking

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shadownrx/apisquare/llms.txt

Use this file to discover all available pages before exploring further.

​

Architecture Overview

1. Telegram Bot — Users interact entirely through inline keyboard buttons and text messages. The bot holds per-user conversation state in Vercel KV so sessions survive server restarts and cold starts.
2. Next.js API Routes (App Router) — A POST /api/webhook handler receives every Telegram update, drives the booking state machine, enforces rate limits, and persists reservations. A GET /api/healthcheck endpoint confirms liveness, and /api/admin/* routes back the dashboard.
3. Vercel KV (Redis) — The single source of truth for conversation state (conv:<chatId>), reservations (reserva:<professional>:<date>:<time>), per-user reservation lists (user:<chatId>:reservas), rate-limit counters, and admin sessions. In local development the app falls back automatically to in-memory storage.
4. Admin Dashboard — A Next.js page at /admin protected by bcrypt credentials and session cookies. Operators can view all reservations, manage configuration, and cancel bookings without touching the database directly.

​

Key Features

• Conversational booking flow — The bot walks users through each step sequentially: select a professional → choose a service → enter your name → pick a date → pick a time slot → confirm. Each step is stored in KV so users can resume after interruptions.
• Real-time availability with overlap prevention — Before displaying time slots, ApiSquare checks existing reservations for the chosen professional and date. Slots are generated from the professional’s schedule and filtered by service duration, ensuring no two bookings ever overlap.
• Per-user rate limiting — Each Telegram user is limited to 20 messages per 60-second window. Excess requests receive an immediate warning and are dropped before the booking logic runs.
• Per-user reservation cap — A maximum of 2 active reservations per user is enforced. Attempting to book a third slot shows a friendly prompt to cancel an existing one first.
• Update deduplication — Every incoming Telegram update_id is checked against KV (or an in-memory Set locally) before processing. Duplicate deliveries from Telegram are silently discarded, preventing double-bookings.
• bcrypt admin authentication with brute-force protection — Admin login compares submitted passwords against a bcrypt hash stored in ADMIN_PASSWORD. After 5 consecutive failed login attempts from the same IP, the account is locked out for 15 minutes.
• In-memory fallback for local development — When KV_REST_API_URL and KV_REST_API_TOKEN are absent, all storage (conversation state, reservations, sessions, rate limits) transparently falls back to in-process Maps and Sets. No Redis credentials are required to run the project locally.
• Optional Google Calendar integration — Confirmed appointments can be pushed to a Google Calendar using a service account key or OAuth credentials. The target calendar is configurable via GOOGLE_CALENDAR_ID.

​

Tech Stack