DEV Community: John

Appointment reminders in a Telegram bot without a scheduler library

John — Sun, 15 Nov 2026 15:42:02 +0000

When I added reminders to a small appointment bot, my first instinct was to reach for a job scheduler: one job per booking, fired at the right time. I ended up with something much smaller: one loop and two columns. Here is why, and how it works.

The problem with one job per booking

A job per booking means every change to a booking has to touch the scheduler too. A client cancels: remove the job. The owner moves an appointment: reschedule the job. The bot restarts: the in-memory jobs are gone unless you add a persistent job store.

That is a second source of truth, and it will drift from the bookings table sooner or later.

Poll the table instead

The bookings table already knows everything needed. So the bot asks it one question every minute: which active bookings start soon and have not been reminded yet?

async def reminder_loop(bot):
    while True:
        try:
            due = store.due_reminders(now())
            for kind, label in (("day", "tomorrow"), ("hours", "soon")):
                for r in due[kind]:
                    try:
                        await bot.send_message(r["user_id"], f"Reminder: you have a booking {label}")
                    except Exception as e:
                        logging.warning("Reminder not delivered: %s", e)
        except Exception:
            logging.exception("Reminder loop error")
        await asyncio.sleep(60)

It is started once next to polling:

task = asyncio.create_task(reminder_loop(bot))
try:
    await dp.start_polling(bot)
finally:
    task.cancel()

Cancelled bookings drop out on their own because the query only looks at active rows. Moved bookings are picked up at their new time. After a restart nothing is lost, because nothing lived in memory.

Two flags, not one

The bot sends two reminders: a day before and two hours before. Each gets its own column, reminded_day and reminded_hours, both 0 by default.

def due_reminders(self, now):
    out = {"day": [], "hours": []}
    for kind, col, delta in (("day", "reminded_day", timedelta(hours=24)),
                             ("hours", "reminded_hours", timedelta(hours=2))):
        rows = self.db.execute(
            "SELECT * FROM bookings WHERE status='active' AND %s=0 "
            "AND start>? AND start<=?" % col,
            (now.isoformat(), (now + delta).isoformat())).fetchall()
        with self.db:
            for r in rows:
                self.db.execute("UPDATE bookings SET %s=1 WHERE id=?" % col, (r["id"],))
        out[kind] = rows
    return out

The column name is interpolated into the SQL, which is safe here only because it comes from a fixed tuple in the code and never from user input. All values still go through parameters.

Three details that matter

Mark before you send. The flag is set when the row is selected, not after the message is delivered. If sending fails, the client misses one reminder. The other order risks sending the same reminder every minute while Telegram is returning errors, which is worse.

Catch errors per message. A client can block the bot at any time, and send_message then raises. Without the inner try, one blocked user stops reminders for everyone after them in the list.

Short-notice bookings. Someone books at 10:00 for 12:00. That booking is inside both windows at once, so a naive loop sends "tomorrow" and "soon" back to back. I still mark both flags, but drop the day-before message when the visit is less than three hours away:

out["day"] = [r for r in out["day"]
              if datetime.fromisoformat(r["start"]) - now > timedelta(hours=3)]

When this is not enough

Polling every minute means a reminder can be up to a minute late, which is fine for appointments. It also assumes one bot process. With several workers you would need to claim rows atomically, for example with a single UPDATE ... WHERE reminded_day=0 RETURNING *. For a bot serving one business, the loop above is enough.

The full bot

This reminder code is part of a complete appointment bot: booking flow, double-booking protection, owner notifications and admin commands. I wrote about the slot logic in a previous post. If you want the whole thing as working code, I sell the template here: https://payhip.com/b/VH20Y ($19, source code and setup guide).

How to stop double bookings in a Telegram bot (Python + SQLite)

John — Sun, 15 Nov 2026 15:40:17 +0000

A booking bot looks simple until two clients tap the same time slot in the same second. Here is the approach I used in a small appointment bot for barbershops and salons. It needs no external services, only SQLite.

1. Never store free slots

The tempting design is a slots table with a taken flag. It goes stale the moment working hours change, and it gives you two things to keep in sync.

Instead, store only bookings and compute free slots when asked:

def free_slots(self, master, day, duration_min, now):
    hours = self.cfg["work_hours"].get(str(day.isoweekday()))
    if not hours:
        return []          # day off
    step = timedelta(minutes=self.cfg.get("slot_step_min", 30))
    need = timedelta(minutes=duration_min)
    cur = datetime.combine(day, time.fromisoformat(hours[0]))
    end = datetime.combine(day, time.fromisoformat(hours[1]))
    earliest = now + timedelta(minutes=self.cfg.get("min_notice_min", 60))
    busy = self._busy(master, day)   # [(start, end), ...] of active bookings
    slots = []
    while cur + need <= end:
        if cur >= earliest and all(cur + need <= b0 or cur >= b1 for b0, b1 in busy):
            slots.append(cur)
        cur += step
    return slots

The overlap test is the whole trick: a candidate is free if, for every existing booking, it ends before that booking starts or starts after it ends. This also handles services of different lengths, so a 90-minute service will not be offered 30 minutes before a taken slot.

2. Check and insert in one transaction

The slot list a client sees can be seconds old. So the final step re-checks inside the same transaction that writes the booking:

def book(self, user_id, client_name, phone, service, master, start, now):
    svc = self.service(service)
    with self.db:  # one transaction: check and insert together
        if start not in self.free_slots(master, start.date(), svc["duration_min"], now):
            return None
        cur = self.db.execute("INSERT INTO bookings(...) VALUES (...)", (...))
        return cur.lastrowid

If book returns None, the bot tells the client the slot was just taken and shows the menu again. With a single bot process and SQLite this is enough. If you ever run several workers, add a unique index on (master, start) for active bookings as a second line of defence.

3. Send each reminder exactly once

Reminders are a loop that runs every minute. Without care it sends the same reminder sixty times an hour. One flag per reminder type fixes that (simplified):

rows = db.execute(
    "SELECT * FROM bookings WHERE status='active' AND reminded_day=0 "
    "AND start>? AND start<=?", (now, now + timedelta(hours=24))).fetchall()
for r in rows:
    db.execute("UPDATE bookings SET reminded_day=1 WHERE id=?", (r["id"],))

One edge case: someone books for two hours from now. Both the "day before" and the "two hours before" windows match at once. I mark both as sent but only deliver the short-notice one.

4. Test the logic without Telegram

Because the booking logic takes now as an argument and never touches the Telegram API, it runs against an in-memory database:

def test_same_slot_twice():
    b = Booking(cfg, ":memory:")
    start = datetime(2026, 11, 16, 12, 0)
    assert b.book(1, "Ivan", "+100000000", "Haircut", "Alex", start, MON)
    assert b.book(2, "Peter", "+100000001", "Haircut", "Alex", start, MON) is None

Passing the clock in as a parameter is what makes reminder and "minimum notice" rules testable at all.

The full bot

The snippets above come from a complete bot: service, specialist, day and time selection, client cancellations, owner notifications and admin commands. If you would rather start from working code than assemble it yourself, I sell the template here: https://payhip.com/b/VH20Y ($19, source code and setup guide).

Questions about any of the parts are welcome in the comments.