Appointment reminder on WhatsApp through the API: routine, confirmation and LGPD

The source of truth is your schedule: a database with the appointments table, an ERP or Google Calendar (see the Google Calendar integration). This recipe assumes an appointments table with status, time, name, phone, a consent_whatsapp field (the patient agreed to receive reminders) and reminder_sent_at (null until sent). If your schedule is a closed SaaS, the path is usually a webhook or an export; check what it offers before promising the reminder.

The consent field is not decoration. Health appointment data is personal data, and almost always sensitive by context. Collect consent at registration or when booking ('may I remind you of the appointment on WhatsApp?') and check the field in the send filter.

The routine runs every 15 minutes and fetches confirmed appointments that start 23 to 24 hours ahead, with no reminder yet and with consent. The one-hour window, together with the reminder_sent_at filter, makes each appointment get picked up only once. Before sending, the routine 'claims' the row with a conditional UPDATE: if two runs overlap, only one manages to mark the send. If the send fails, the mark is undone so the next run tries again.

The random gap of a few seconds between messages avoids bursts. For a clinic's reminders the volume is low, but the principle holds: a human pace reduces risk. The send uses POST /api/v1/{instanceId}/send/text with number and text, and ZapZap also applies delay and the typing indicator by default (anti-ban). Check beforehand that the number has WhatsApp with the chat/check route, described in the reference.

// Runs every 15 minutes (cron, queue worker or n8n schedule). Appointments come from YOUR system.
async function remindAppointments() {
  const rows = await db.query(`
    SELECT id, patient_name, patient_phone, starts_at
    FROM appointments
    WHERE status = 'confirmed' AND reminder_sent_at IS NULL AND consent_whatsapp = TRUE
      AND starts_at BETWEEN now() + interval '23 hours' AND now() + interval '24 hours'`);

  for (const a of rows.rows) {
    // claim before sending: a second run cannot pick the same row
    const claim = await db.query("UPDATE appointments SET reminder_sent_at = now() WHERE id = $1 AND reminder_sent_at IS NULL", [a.id]);
    if (!claim.rowCount) continue;

    const when = new Date(a.starts_at).toLocaleString("pt-BR", { dateStyle: "short", timeStyle: "short", timeZone: "America/Sao_Paulo" });
    try {
      await sendWhatsApp(a.patient_phone, "Oi, " + a.patient_name.split(" ")[0] + ". Lembrete da sua consulta amanhã, " + when + ". Responda 1 para confirmar ou 2 para remarcar.");
    } catch (e) {
      await db.query("UPDATE appointments SET reminder_sent_at = NULL WHERE id = $1", [a.id]); // let the next run retry
      console.error("reminder failed", a.id, e.message);
    }
    await new Promise((r) => setTimeout(r, 4000 + Math.random() * 6000)); // human-like gap between sends
  }
}

// Shared helper: one send through the ZapZap API
async function sendWhatsApp(number, text) {
  const r = await fetch(`https://api.zapzapapi.com/api/v1/${process.env.ZAPZAP_INSTANCE}/send/text`, {
    method: "POST",
    headers: {
      "x-api-key": process.env.ZAPZAP_API_KEY,
      "x-api-secret": process.env.ZAPZAP_API_SECRET,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ number, text }),
  });
  if (!r.ok) throw new Error("ZapZap " + r.status + ": " + (await r.text()));
}

For the reply to work, the instance has to deliver incoming messages to your server: register the URL with PUT /api/v1/instances/{id}/webhook and the messages event (set up the webhook). Discard fromMe messages, or your own automatic reply may re-enter the flow and create a loop. Check the exact payload format with a real message before writing the code; the example below shows only the logic.

Handle unexpected replies carefully: 'ok', 'yes' and 'confirm' are also confirmations. Map a few variations and, if you do not understand, do not answer on your own: forward it to the front desk. To validate the X-ZapZap-Signature header and discard repeated deliveries, follow the guide on webhooks in production.

// Receive the patient's "1" or "2" (message webhook registered with PUT /api/v1/instances/{id}/webhook, event "messages")
app.post("/zapzap", express.json(), async (req, res) => {
  res.sendStatus(200);
  const m = req.body; // check the exact shape with a real message first (see the webhooks reference)
  if (m.fromMe) return; // never react to your own messages, or an automatic reply answers itself in a loop
  const text = String(m.text || "").trim();
  if (text === "1") await markConfirmed(m.from);
  else if (text === "2") await askReschedule(m.from);
});

Say the essentials: the patient's name, the day and time, the clinic's name and how to confirm or reschedule. Do not write the procedure, the name of a doctor in a sensitive specialty, an exam result or a diagnosis. WhatsApp is a channel where the device may be with someone else, and health data in a notification is a leak waiting to happen. 'Appointment with Dr. Ana, tomorrow at 2 pm' is enough.

If the clinic has requirements from its professional council on communicating with patients, follow your council's rules. This recipe is technical and does not replace legal or ethical guidance.

An appointment reminder to someone who booked with you is the lowest-risk use there is. Even so, ZapZap connects numbers through an unofficial, managed channel, and no feature guarantees the absence of blocking. Keep the pace, do not send to anyone who asked to stop and do not use the reminder to advertise a promotion.

Test first with fictional appointments and with your number. Check the time zone (the example uses America/Sao_Paulo), the 23 to 24 hour window and, above all, that running the routine twice in a row does not produce a second message. For specific segments, see the pages for clinics and dentists.