Automate WhatsApp Appointment Reminders (With Code)
Any statistics or percentages in this article are general industry figures or illustrations, not QuackAPI measurements or promises. Results depend on your audience, consent and sending patterns. QuackAPI connects to WhatsApp as a linked device (an unofficial method), so read our risk and acceptable use policy before sending.
Why reminders are the best first WhatsApp automation
Clinics, salons, tutors, repair shops and consultants all lose time and money when people forget appointments. A short reminder on the channel the customer already reads is cheap to build and easy to explain, and it only needs two things: a list of upcoming appointments and a way to send a message.
This guide builds a small scheduled job. Every few minutes it finds appointments that need a reminder, sends one WhatsApp message each, records that it did, and never sends the same reminder twice. It also covers replies, opt-outs and what not to automate.
Only message people who have agreed to hear from you. QuackAPI is a linked-device service, not Meta's official Cloud API, so WhatsApp can restrict a number it considers abusive. Read the acceptable use policy before you automate anything.
Rules before code
Reminders are the kind of message people expect, which is why they work, but the same rules apply to them as to everything else you send.
| Rule | Why |
|---|---|
| Only message people who gave you their number for this purpose | A customer who booked with you expects a reminder. A cold list does not. |
| Say who you are in the message | Include your business name so the message is recognisable. |
| Make stopping easy | Tell people they can reply STOP, and honour it immediately. |
| Keep the text short and useful | Date, time, place and how to change it. No promotions. |
| Do not send at night | Respect the customer's local time. Send between sensible hours only. |
The data you need
Whatever system holds your appointments, you need these fields per booking: the customer's WhatsApp number in international format, their name, the appointment time stored in UTC, the customer's time zone, and two timestamps that start empty, reminder_24h_sent_at and reminder_2h_sent_at. Those timestamps are what makes the job safe to run repeatedly.
Also keep an opted_out flag per customer. The job must skip anyone who has asked to stop.
-- example table
CREATE TABLE appointments (
id serial PRIMARY KEY,
customer_name text NOT NULL,
phone text NOT NULL, -- 923001234567
timezone text NOT NULL, -- Asia/Karachi
starts_at timestamptz NOT NULL,
opted_out boolean NOT NULL DEFAULT false,
confirmed boolean NOT NULL DEFAULT false,
reminder_24h_sent_at timestamptz,
reminder_2h_sent_at timestamptz
);The scheduled job in Node.js
This example uses node-cron to run every five minutes and the pg library for the query. Any scheduler works: a cron entry, a queue worker or a cloud scheduler. The important part is the order of operations. Claim the row first, then send, so two overlapping runs cannot both send it.
The UPDATE ... RETURNING statement marks reminders as sent and returns only the rows this run claimed. The extra IS NULL check on the outer query matters: if two runs overlap, the second one re-checks the row after the first commits and skips it. If the send then fails, the code clears the marker so the next run tries again.
const cron = require("node-cron");
const { Pool } = require("pg");
const db = new Pool({ connectionString: process.env.DATABASE_URL });
const API = "https://quackapi.com/v1/messages/chat";
async function sendWhatsApp(to, body) {
const res = await fetch(API, {
method: "POST",
headers: { "Content-Type": "application/json", "x-api-key": process.env.QUACKAPI_KEY },
body: JSON.stringify({ deviceId: Number(process.env.QUACKAPI_DEVICE), to, body }),
});
const data = await res.json().catch(() => ({}));
if (!res.ok) throw new Error(res.status + " " + (data.message || "send failed"));
return data.messageId;
}
function whenText(startsAt, tz) {
return new Intl.DateTimeFormat("en-GB", {
weekday: "long", day: "numeric", month: "long", hour: "numeric", minute: "2-digit", timeZone: tz,
}).format(startsAt);
}
// kind is "24h" or "2h"; windowSql picks the bookings whose reminder is due now
async function runReminders(kind, minHours, maxHours) {
const col = "reminder_" + kind + "_sent_at";
// Claim rows in one statement so overlapping runs cannot double send.
const { rows } = await db.query(
"UPDATE appointments SET " + col + " = now() " +
"WHERE " + col + " IS NULL AND id IN (SELECT id FROM appointments " +
" WHERE " + col + " IS NULL AND NOT opted_out " +
" AND starts_at > now() + make_interval(hours => $1) " +
" AND starts_at <= now() + make_interval(hours => $2) " +
" LIMIT 20) " +
"RETURNING id, customer_name, phone, timezone, starts_at",
[minHours, maxHours]
);
for (const a of rows) {
const text =
"Hi " + a.customer_name + ", this is a reminder from Bright Dental about your appointment on " +
whenText(a.starts_at, a.timezone) + ". Reply YES to confirm or call us to reschedule. Reply STOP to stop reminders.";
try {
await sendWhatsApp(a.phone, text);
} catch (err) {
console.error("reminder failed", a.id, err.message);
// release the claim so the next run retries (skip this for 400 validation errors)
await db.query("UPDATE appointments SET " + col + " = NULL WHERE id = $1", [a.id]);
}
await new Promise((r) => setTimeout(r, 4000)); // pause between messages
}
}
cron.schedule("*/5 * * * *", async () => {
await runReminders("24h", 23, 24); // about a day ahead
await runReminders("2h", 1, 2); // about two hours ahead
});Why this design is safe to run repeatedly
Three details do the work. First, each reminder has its own timestamp, so the 24 hour and 2 hour reminders are independent. Second, the update-then-send order means a crash or an overlapping run cannot send the same reminder twice. Third, the LIMIT 20 and the pause keep each run small, so a backlog after downtime is worked through gradually instead of being sent in one burst.
The one-hour wide windows also mean the job still catches a booking if a run is delayed by a few minutes. If you make the window narrower than your run interval you will miss appointments.
Handle YES and STOP replies
Set a webhook URL on the device and QuackAPI will POST incoming messages to your server as JSON with the event message.received, the sender in from and the text in content. Match the sender to a customer, then act on the text.
app.post("/webhooks/whatsapp", express.json(), async (req, res) => {
res.sendStatus(200); // answer quickly, then do the work
const { event, from, content, messageId } = req.body;
if (event !== "message.received") return;
const text = String(content || "").trim().toUpperCase();
if (text === "STOP") {
await db.query("UPDATE appointments SET opted_out = true WHERE phone = $1", [from]);
} else if (text === "YES") {
await db.query("UPDATE appointments SET confirmed = true WHERE phone = $1 AND starts_at > now()", [from]);
}
});Treat webhooks carefully
Webhooks are not signed today, so keep the URL long and unguessable, validate the fields you use and use messageId to ignore repeats. Never let a webhook change anything more serious than a flag such as opted_out or confirmed. The webhook reference describes every event, including message.failed, which is useful to alert you when a reminder could not be delivered.
What not to automate
Do not use WhatsApp as the only channel for anything where a missed or late message could cause serious harm, such as medical emergencies or safety alerts. Delivery cannot be guaranteed, the number can be disconnected and WhatsApp can restrict an account. Keep a second channel such as SMS or email for anything critical, and watch your device status in the dashboard. If the device disconnects, QuackAPI can email you so reminders do not silently stop.
Frequently asked questions
How far ahead should I send an appointment reminder?
Do I need approved message templates?
Can I do this without writing code?
How do I stop duplicate reminders?
Where to go next
Read the Node.js guide for more on the request, the best practices for WhatsApp messaging for tone and timing, and the n8n guide if you would rather build this visually.