Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 37 ยท Projects and Practice

Project: A Reminder Bot

Build a complete reminder bot core in Node.js: parse durations, store reminders in SQLite, run a scheduler that survives restarts, list and cancel reminders, with tests.

Reminders are the classic first useful bot: "remind me in 2 hours to call Sam". They combine nearly everything from this chapter: strict argument parsing, a database, a scheduler that survives restarts, rate-aware sending and a command handler. In this project you build the whole core in one runnable file, using a fake API in place of Telegram or Discord, so you can see every step work.

The finished bot supports:

  • /remind <duration> <text> creates a reminder (30m, 2h, 1d).
  • /reminders lists your pending reminders.
  • /cancel <id> removes one of your reminders.
  • A scheduler delivers due reminders, even ones that came due while the bot was offline.

Design decisions

flowchart TD
    M["Message: /remind 2h call Sam"] --> P["parseCommand"]
    P --> V["validate duration and text"]
    V --> DB[("SQLite: reminders")]
    S["Scheduler tick (every few seconds)"] --> Q["SELECT due reminders"]
    DB --> Q
    Q --> SEND["api.sendMessage"]
    SEND --> DONE["mark as sent"]

The database is the single source of truth. The scheduler never keeps its own list in memory.

Three choices make it robust. First, reminders live in SQLite with an absolute due time (a timestamp), not "a timer for 2 hours": timers vanish on restart, rows do not. Second, the scheduler polls the table every few seconds and asks "what is due now?", so overdue reminders are delivered after downtime. Third, a reminder is marked as sent only after the API call succeeds, and failures are retried, so a network blip does not lose it.

The complete program

Read it top to bottom: storage, parsing, command handlers, scheduler, then a scripted scenario at the end.

Node.js Reminder bot core

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Walk through the important parts

Absolute due times. due_at = now + delay is computed once and stored. After a restart the bot only needs to look at the clock. Compare this with setTimeout(() => ..., 7_200_000), which is lost when the process ends and limited to about 24.8 days anyway.

The partial index. CREATE INDEX ... WHERE sent_at IS NULL indexes only unsent reminders, so the "what is due?" query stays fast even after a million reminders have been delivered.

Ownership checks. DELETE ... WHERE id = ? AND user_id = ? means a user cannot cancel someone else's reminder by guessing an ID. This is the same idea as authorization in a web app: every query that acts on a record includes the owner.

Limits. The per-user cap, the text length and the minimum and maximum durations protect the bot from abuse, as discussed in anti-spam and input validation.

Retries with a cap. A reminder that fails to send three times stays in the table with attempts = 3 and is no longer picked up. In a real bot you would log it and alert (see logging and monitoring). If the user blocked the bot (403), mark the reminder as dead immediately.

Running the scheduler for real

In production the scheduler is one line:

JavaScript
setInterval(() => tick().catch((err) => logger.error("tick failed", err)), 5000).unref();

Because the query asks "due at or before now", a missed tick is harmless. Five seconds of accuracy is plenty for human reminders. Remember that Telegram allows about one message per second per chat; if a user set fifty reminders for the same minute, send them through the paced queue from rate limits and backoff.

Extensions to try

  1. Time zones: store the user's zone as a setting (per-user settings) and accept /remind at 18:30 ... using Intl.DateTimeFormat to convert.
  2. Repeating reminders: add a nullable repeat_ms column; after sending, insert the next occurrence instead of just marking it sent.
  3. Snooze buttons: attach an inline keyboard (Telegram) or a button component (Discord) that adds another 10 minutes.
  4. Tests: copy the pattern from testing bots with fakes: advance the fake clock to just before and just after due_at and assert on sent.
  5. Discord version: wire handleCommand to slash commands with duration and text options; the core does not change.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why store an absolute due_at timestamp instead of starting a timer?

    The scheduler only compares due_at with the clock, so downtime does not lose reminders.
  2. 2. What does the WHERE id = ? AND user_id = ? in the cancel statement prevent?

    Every statement that changes a record should include the owner as part of the condition.
  3. 3. Why is a reminder marked as sent only after the API call succeeds?

    Marking first would lose reminders when the send fails.
  4. 4. What happens to a reminder that came due while the bot was offline?

    The tick query selects everything with due_at <= now, including overdue rows.

Summary

  • Keep reminders as rows with absolute due times; the scheduler polls for due rows.
  • Validate duration, text length and per-user limits; scope every update and delete by owner.
  • Mark as sent only after success, retry a limited number of times and alert on dead reminders.
  • The command core is platform-neutral: only the adapter and api differ between Telegram and Discord.

Next: Project: a poll bot