Overdue boleto reminder on WhatsApp: a recipe with webhook, queue and opt-out

Define the rule in one sentence: on the day the charge falls due, a helpful reminder; three days later, if it is still open, a second one; after that, nothing on WhatsApp. Two messages are enough for someone who forgot, and someone who does not answer two probably needs another channel (a call, email, negotiation). More than that raises reports and the risk of the number being limited.

Golden rule of tone: reminder, not aggressive billing. Brazil's Consumer Defense Code (art. 42) forbids exposing a delinquent consumer to ridicule or embarrassment, so no text that accuses, threatens or mentions credit bureau listing. If your operation has old debt, handle it with your legal counsel; this recipe is for a delay of days.

Asaas sends PAYMENT_OVERDUE when the charge falls due. Configure the webhook with that event and an authToken (32 to 255 characters, no spaces), and validate the asaas-access-token header on every request. There is another event that looks useful and is not: PAYMENT_BANK_SLIP_CANCELLED only indicates that the boleto registration was canceled after the due date, and it does not mean the charge was removed.

Remember that delivery is at least once: store the event id with a uniqueness constraint before scheduling anything, as in the Pix paid recipe. The Asaas page has the event table and the paused queue rules.

The core of the recipe is in the worker: it never trusts what the event said hours or days ago. Before sending, it queries the charge in Asaas and only proceeds if the status is still OVERDUE. A customer who paid between the event and the reminder gets nothing. Check the Asaas reference for the status values of your API version before going to production.

Scheduling (the 'schedule' queue) is yours: it can be a table with an execution time and a cron every minute, a queue like BullMQ or an n8n flow with a Wait node. The example below shows the logic without tying it to a tool.

// POST /asaas : first reminder when a charge becomes overdue, second one 3 days later if still unpaid
app.post("/asaas", express.json(), async (req, res) => {
  if (req.get("asaas-access-token") !== process.env.ASAAS_WEBHOOK_TOKEN) return res.sendStatus(401);
  const { id, event, payment } = req.body;
  const fresh = await saveEventOnce(id, req.body); // INSERT ... ON CONFLICT DO NOTHING
  res.sendStatus(200);
  if (!fresh || event !== "PAYMENT_OVERDUE") return;

  if (await isOptedOut(payment.customer)) return;   // suppression list, see the opt-out section
  await schedule("reminder-1", payment.id, 0);      // your queue: run now
  await schedule("reminder-2", payment.id, 3 * 24 * 3600); // run in 3 days
});

// Worker: always re-check the charge right before sending
async function runReminder(kind, paymentId) {
  const p = await fetch("https://api.asaas.com/v3/payments/" + paymentId, {
    headers: { access_token: process.env.ASAAS_API_KEY },
  }).then((r) => r.json());
  if (p.status !== "OVERDUE") return;               // paid, canceled or deleted meanwhile: say nothing
  const c = await fetch("https://api.asaas.com/v3/customers/" + p.customer, {
    headers: { access_token: process.env.ASAAS_API_KEY },
  }).then((r) => r.json());
  const phone = String(c.mobilePhone || c.phone || "").replace(/\D/g, "");
  if (phone.length < 10 || (await isOptedOut(p.customer))) return;
  const first = c.name.split(" ")[0];
  const text = kind === "reminder-1"
    ? "Oi, " + first + ". Sua cobrança venceu e ainda consta em aberto. Se já pagou, pode ignorar. Se precisar de uma segunda via ou de outra data, é só responder aqui. Para não receber esses avisos, responda PARAR."
    : first + ", passando só para confirmar se deu tudo certo com a sua cobrança. Posso ajudar com a segunda via? Para não receber mais avisos, responda PARAR.";
  await sendWhatsApp(phone.startsWith("55") ? phone : "55" + phone, text);
}

// 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()));
}

Every message in the example ends with 'reply STOP'. That only counts if someone reads the reply. Register the instance's incoming messages webhook (how to set it up), discard your own messages (the fromMe field) and, when the text is STOP, store the customer in a suppression list that the isOptedOut function checks. Without that list, the stop button is decoration, and it is the first thing an annoyed customer will test.

Also record the reason and date of each send. If one day you need to explain why a customer received a message, the log is your defense. The guide on LGPD on WhatsApp lists what to record.

On Kiwify, a generated boleto becomes the boleto_gerado event (webhook_event_type billet_created), and payment becomes compra_aprovada. Kiwify has no 'boleto overdue' trigger: the usual pattern is to wait some time after the boleto is generated and check whether the purchase was approved, which is exactly what the assistant flow does with the 1-hour second reminder. See the Kiwify page.

On Eduzz, myeduzz.invoice_expired indicates an expired invoice and the payload of open invoices carries bankslipUrl and saleRecoveryUrl, which can go into the message. The Eduzz page explains x-signature. On both, the phone comes in the payload, and the Recuperar vendas assistant covers the Pix and boleto cases with no code.

Test with your number and a Sandbox charge. Confirm that someone who pays between the two reminders does not get the second. Confirm that STOP really blocks. Confirm that the text threatens nothing. And remember that ZapZap connects numbers through an unofficial, managed channel: no setting guarantees the absence of blocking, and the combination of few messages, a respectful tone and a clean list is what reduces the risk.