Lembretes de agendamento pelo WhatsApp com confirmação do cliente
Envie lembretes de agendamento pelo WhatsApp na véspera e no dia, receba a confirmação do cliente por webhook e atualize a agenda sem ninguém digitar.
Todo negócio que vive de horário marcado conhece o problema: o cliente esquece, não avisa, e a cadeira ou a sala fica vazia. Clínicas, consultórios, salões, barbearias e estúdios costumam resolver isso com alguém da recepção mandando mensagem um por um no fim da tarde, lendo as respostas no celular e riscando a agenda à mão.
Esse trabalho é perfeito para uma integração. O seu sistema de agenda já sabe quem vem amanhã e a que horas. Falta só mandar o lembrete pelo WhatsApp, que é onde o cliente de fato lê, e trazer a resposta de volta para a agenda sem ninguém copiar nada.
Este guia mostra o fluxo completo com a apiwpp: quando enviar, como montar a mensagem, como a resposta do cliente chega ao seu sistema pelo webhook e o que muda na agenda. Também explica por que o lembrete não sai no mesmo segundo em que você chama a API, e os cuidados que mantêm o número saudável.
Véspera e dia: os dois lembretes que funcionam
O desenho mais comum usa dois avisos por horário marcado:
| Lembrete | Quando enviar | Objetivo |
|---|---|---|
| Véspera | Na tarde do dia anterior, em horário comercial | Pedir a confirmação e abrir espaço para remarcar |
| No dia | Algumas horas antes do atendimento | Lembrar o horário e o endereço, sem pedir nada |
O lembrete da véspera é o que pede resposta: dá tempo de oferecer o horário a outra pessoa se o cliente não puder ir. O do dia é curto e informativo. Se o cliente já confirmou na véspera, muitos negócios nem enviam o segundo, e isso é uma boa escolha: menos mensagens, menos chance de incomodar.
Para uma clínica, o lembrete da véspera pode trazer o nome do profissional e uma orientação de preparo. Para uma barbearia, basta o horário e o nome do barbeiro. Em qualquer caso, a mensagem deve caber na tela do celular sem rolar.
O fluxo: da agenda ao WhatsApp e de volta
A integração tem quatro passos, e só um deles acontece na apiwpp:
- O seu sistema decide a hora. Um job agendado (um cron a cada poucos minutos, por exemplo) procura os horários que precisam de lembrete e ainda não receberam.
- O seu sistema chama a API. Cada lembrete é um
POST /connections/{id}/send, com umclientRefque identifica aquele aviso. - A fila da apiwpp envia no ritmo que protege o número e conta o que aconteceu pelos eventos
message.deliverye, se o envio não puder acontecer,message.send_failed. - O cliente responde e a resposta chega ao seu webhook como
message.incoming. O seu sistema interpreta o texto e atualiza a agenda.
Repare que a API não tem um campo para "enviar amanhã às 17h". Quem decide o momento é o seu sistema, que chama a API na hora em que o lembrete deve sair. Isso é bom: a regra de negócio (quais horários, quantas horas antes, pular quem já confirmou) fica no seu código, onde é fácil de mudar.
Monte a mensagem como template
Um lembrete é sempre o mesmo texto com dados diferentes. Em vez de montar a frase no código, crie um template com variáveis uma vez, com POST /connections/{id}/templates:
curl -X POST https://api.apiwpp.com/connections/$ID/templates \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"lembrete_vespera","body":"Olá, {{nome}}! Lembrete do seu horário amanhã às {{hora}} com {{profissional}}. Responda 1 para confirmar ou 2 para remarcar."}'
Depois, cada envio passa só o nome do template e as variáveis. Se faltar alguma, a API responde 400 com a lista em missingVariables, e nada é enfileirado:
curl -X POST https://api.apiwpp.com/connections/$ID/send \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"5511988887777","template":"lembrete_vespera","variables":{"nome":"Maria","hora":"10h","profissional":"Dra. Paula"},"clientRef":"agenda-4821-vespera"}'
{
"jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
"scheduledAt": 1785960300000,
"position": 4
}
Templates também ajudam o número: cada mensagem sai com o nome e o horário daquela pessoa, e não como um texto idêntico repetido dezenas de vezes.
Use um clientRef por lembrete
O clientRef é a sua chave de idempotência. Use algo estável como agenda-<id>-vespera e agenda-<id>-dia. Se o seu job cair no meio, rodar de novo ou a requisição esgotar o tempo, repetir o envio com o mesmo clientRef devolve o job original com "duplicate": true, em vez de mandar o lembrete duas vezes. Ninguém gosta de receber o mesmo aviso em dobro, e isso é um motivo clássico de denúncia.
O mesmo clientRef volta nos eventos message.delivery e message.send_failed, então o seu sistema sabe a qual horário cada evento pertence. O conceito tem uma explicação curta no glossário de idempotência.
Por que o lembrete não sai no mesmo segundo
A chamada de envio não espera a mensagem sair. Ela coloca o lembrete na fila do número e responde 202 na hora, com scheduledAt (o horário previsto, em milissegundos unix) e position (o lugar na fila).
A fila existe para proteger o número. Os limites padrão por número são:
- 3 mensagens por minuto, 60 por hora e 200 por dia;
- um intervalo aleatório de 3 a 8 segundos entre dois envios;
- pelo menos 30 segundos entre duas mensagens para o mesmo destinatário;
- 100 destinatários novos a cada 24 horas, contando como novo quem não trocou mensagem com o número nos últimos 28 dias.
Na prática, isso muda como você agenda. Se a agenda de amanhã tem 90 horários e o job dispara todos às 17h, a fila vai espalhar os envios por cerca de uma hora e meia, porque sai no máximo 60 por hora. Os últimos lembretes chegam perto das 18h30. Para uma barbearia com 20 horários, a diferença é de minutos. Para uma clínica grande, vale começar os envios da véspera mais cedo, no meio da tarde.
Também dá para fazer as contas do dia: com dois lembretes por horário, o limite de 200 mensagens diárias cobre por volta de 100 atendimentos, antes de contar as respostas que o seu sistema manda. Se a agenda passa disso, divida os atendimentos entre números diferentes (por unidade ou por profissional), cada um com a própria fila, ou envie só o lembrete da véspera.
Nos primeiros 14 dias depois de conectar um número, os limites são menores e sobem por etapas. O guia de aquecimento de número traz a tabela; se você está começando agora, rode os lembretes para uma parte da agenda na primeira semana.
Não deixe o lembrete chegar de madrugada
A fila não sabe qual é o horário comercial do seu negócio. Quem cuida disso é o seu sistema, olhando o scheduledAt da resposta. Se o horário previsto ficou tarde demais, cancele o envio com DELETE /connections/{id}/queue/{jobId} enquanto ele ainda não saiu, e conte com o lembrete do dia.
Um job em Node.js que faz tudo isso cabe em poucas linhas:
const API = 'https://api.apiwpp.com'
const headers = {
Authorization: `Bearer ${process.env.APIWPP_KEY}`,
'Content-Type': 'application/json',
}
type Appointment = { id: number; phone: string; name: string; time: string; professional: string }
// Latest acceptable delivery time for the eve reminder: 20:00 in São Paulo
function latestAllowed(date: Date): number {
const day = date.toLocaleDateString('en-CA', { timeZone: 'America/Sao_Paulo' })
return new Date(`${day}T20:00:00-03:00`).getTime()
}
export async function sendEveReminder(connectionId: string, appt: Appointment) {
const res = await fetch(`${API}/connections/${connectionId}/send`, {
method: 'POST',
headers,
body: JSON.stringify({
to: appt.phone,
template: 'lembrete_vespera',
variables: { nome: appt.name, hora: appt.time, profissional: appt.professional },
clientRef: `agenda-${appt.id}-vespera`,
}),
})
if (res.status === 429) {
// new_recipient_cap_reached: nothing was queued; try again after Retry-After
return { status: 'retry-later', afterSeconds: Number(res.headers.get('Retry-After') ?? '3600') }
}
if (!res.ok) throw new Error(`Send refused: ${res.status} ${await res.text()}`)
const job = (await res.json()) as { jobId: string; scheduledAt: number; duplicate?: boolean }
if (job.scheduledAt > latestAllowed(new Date())) {
// Too late to be polite: cancel while it is still queued, keep the same-day reminder
await fetch(`${API}/connections/${connectionId}/queue/${job.jobId}`, { method: 'DELETE', headers })
return { status: 'skipped', jobId: job.jobId }
}
return { status: 'queued', jobId: job.jobId, scheduledAt: job.scheduledAt }
}
Grave o jobId e o scheduledAt no horário marcado. Eles ajudam a responder a pergunta que a recepção sempre faz: "o lembrete da Maria já foi?". A página de integração com Node.js mostra o mesmo envio com o webhook ao lado.
A resposta do cliente chega pelo webhook
Quando o cliente responde, a apiwpp envia um POST ao webhook do projeto com o evento message.incoming. O texto vem em data.body e o remetente em data.phone (no formato E.164, com +) e em data.jid:
{
"type": "message.incoming",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "clinica-centro",
"timestamp": "2026-08-05T20:14:09.000Z",
"data": {
"from": "[email protected]",
"jid": "[email protected]",
"phone": "+5511988887777",
"body": "1",
"timestamp": 1785960849
}
}
Antes de processar, verifique a assinatura HMAC do cabeçalho X-Sales-Signature e responda 2xx em até 10 segundos, deixando o trabalho pesado para depois. O passo a passo está no guia de webhooks do WhatsApp.
Case a resposta com o horário certo
A resposta não diz a qual horário se refere. O seu sistema precisa descobrir: procure o agendamento com lembrete enviado e ainda sem resposta para aquele remetente. Duas precauções evitam casar errado:
- Guarde o
jide ophonedo lembrete. O eventomessage.deliverydo lembrete traz o seuclientRefjunto com ojide ophonedo destinatário, exatamente como o WhatsApp registrou o número. Contas antigas sem o nono dígito respondem com umphonediferente do que você tem no cadastro; comparando com o que veio nomessage.delivery, a resposta casa mesmo assim. - Trate o remetente sem telefone. Às vezes a mensagem chega identificada só por um LID (
…@lid) ephone: null. Quando o telefone for descoberto, chega o eventocontact.resolved. Nesse meio-tempo, deixe a resposta pendente em vez de descartá-la. O glossário sobre LID explica o caso.
Depois, interprete o texto com regras simples e tolerantes:
type Reply = 'confirm' | 'reschedule' | 'unknown'
export function parseReply(body: string): Reply {
const text = body.trim().toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '')
if (/^(1|sim|confirmo|confirmado|ok)\b/.test(text)) return 'confirm'
if (/^(2|nao|remarcar|desmarcar)\b/.test(text) || text.includes('remarc')) return 'reschedule'
return 'unknown'
}
Com a resposta interpretada:
- Confirmou: marque o horário como confirmado e, se quiser, mande um "Confirmado, até amanhã!". Não envie o lembrete do dia, ou envie só o endereço.
- Quer remarcar: libere o horário na agenda, avise a recepção e mande um link para escolher outro horário, se o seu sistema tiver um.
- Qualquer outra coisa: encaminhe para uma pessoa. "Posso levar meu filho?" não é confirmação nem cancelamento, e uma resposta automática errada irrita mais do que nenhuma.
A entrega do webhook é pelo menos uma vez: o mesmo evento pode chegar de novo. Faça a mudança de estado idempotente, de modo que confirmar um horário já confirmado não faça nada nem mande uma segunda mensagem.
Reações também contam
Muita gente responde a um lembrete só com um 👍. Isso chega como message.reaction, com o messageId da mensagem que recebeu a reação e o emoji. Como o message.delivery do lembrete trouxe o messageId junto com o seu clientRef, basta guardar esse id no agendamento para tratar o polegar como confirmação. Um emoji vazio quer dizer que a pessoa removeu a reação.
Botões, enquetes e o que funciona hoje
A primeira ideia de quase todo mundo é pôr botões de "Confirmar" e "Remarcar" no lembrete. Hoje a apiwpp não envia botões nem listas interativas. As enquetes estão no roadmap e aparecem como "em breve" nos recursos. O que funciona hoje, em qualquer plano, é a resposta em texto: "Responda 1 para confirmar ou 2 para remarcar".
Na prática, a resposta numérica tem vantagens próprias. Funciona em qualquer versão do WhatsApp, o cliente entende sem explicação e o seu sistema interpreta com uma regra de duas linhas. Aceite também as variações naturais ("sim", "confirmo", "não posso") e mande para uma pessoa o que não reconhecer.
Alguns recursos do plano PRO ajudam no dia a dia dos lembretes:
- Marcar como lida a resposta do cliente, para que ele saiba que a confirmação foi recebida pelo sistema.
- Editar uma mensagem em até 15 minutos depois do envio, útil quando um lembrete saiu com o horário errado.
- Apagar para todos um lembrete enviado por engano, por exemplo para um horário já cancelado.
No plano LITE essas rotas respondem 403 plan_feature_required; o resto do fluxo (envio, templates, fila, webhooks e reações) funciona igual. A diferença entre os planos está em preços.
Cuidados que mantêm o número saudável
Lembrete de agendamento é uma das mensagens mais bem recebidas no WhatsApp: a pessoa marcou o horário e espera ser lembrada. Ainda assim, alguns cuidados fazem diferença:
- Envie só para quem agendou. O lembrete é para quem já é cliente e deixou o número ao marcar. Não use a mesma integração para mandar promoções para toda a base.
- Respeite o horário comercial. Agende os envios da véspera para a tarde e confira o
scheduledAt, como no exemplo acima. - Seja curto e diga quem fala. Nome do negócio, dia, hora, profissional e o que responder. Endereço e orientações cabem no lembrete do dia.
- Não insista. Se o cliente não respondeu, não mande outro lembrete da véspera. O lembrete do dia já é a segunda chance.
- Ofereça uma saída. Quem pedir para não receber lembretes deve ter a preferência gravada no cadastro e respeitada.
- Trate as falhas. Um número que não tem WhatsApp gera
message.send_failedcom o motivonot_on_whatsapp. Marque o cadastro para a recepção ligar em vez de tentar de novo.
Lembre que clientes novos, que nunca trocaram mensagem com o número, contam no teto de 100 destinatários novos por 24 horas. Para uma agenda com muita gente nova, envie a confirmação no momento do agendamento: a partir daí o cliente já conversou com o número e deixa de contar como novo por 28 dias. O guia sobre como evitar o bloqueio do número detalha o resto.
Se o seu produto é um sistema de agenda usado por vários negócios, cada negócio pode conectar o próprio número pela sua tela. O guia sobre WhatsApp dentro do seu SaaS mostra como organizar as conexões e o externalId.
Como começar hoje
- Defina as regras: quais serviços recebem lembrete, quantas horas antes e até que horas um lembrete da véspera pode chegar.
- Crie o template
lembrete_vesperacom as variáveis de nome, hora e profissional, e um template curto para o lembrete do dia. - Escreva o job que procura os horários de amanhã e chama o
/sendcom umclientRefpor lembrete, guardandojobIdescheduledAt. - Configure o webhook do projeto com um segredo e trate
message.delivery,message.incoming,message.reactionemessage.send_failed. - Teste com a sua própria agenda antes de ligar para todos os clientes, e comece com uma parte dos horários enquanto o número aquece.
- Crie sua conta na apiwpp e conecte o número do negócio: são 7 dias de teste com os recursos do PRO (exceto IP dedicado), sem cartão.
Perguntas frequentes
Posso agendar um lembrete para sair num horário específico?
A API não tem um campo de data futura: ela coloca a mensagem na fila na hora em que você chama. Quem escolhe o momento é o seu sistema, com um job que chama o envio quando o lembrete deve sair. A resposta traz o scheduledAt, o horário previsto pela fila, para você conferir se ainda está dentro do horário comercial.
Por que o lembrete demorou alguns minutos para chegar?
Cada número tem uma fila que envia no máximo 3 mensagens por minuto e 60 por hora no padrão, com um intervalo aleatório de 3 a 8 segundos entre os envios. Se muitos lembretes forem disparados juntos, os últimos saem mais tarde. Começar os envios mais cedo ou distribuí-los ao longo da tarde resolve.
Dá para confirmar o agendamento com botões?
Hoje não: a apiwpp não envia botões nem listas interativas, e as enquetes estão em breve. A confirmação por texto, com "responda 1 para confirmar ou 2 para remarcar", funciona em qualquer plano e chega ao seu sistema como message.incoming. Reações como um 👍 também chegam, pelo evento message.reaction.
Como evitar que o cliente receba o mesmo lembrete duas vezes?
Envie cada lembrete com um clientRef estável, como agenda-4821-vespera. Se o seu job repetir a chamada, a API devolve o envio original com "duplicate": true e não enfileira nada. O clientRef fica reservado por 7 dias.
O lembrete de agendamento funciona no plano LITE?
Sim. Envio, templates com variáveis, fila, webhooks e reações fazem parte dos dois planos. O PRO acrescenta marcar como lida, presença, editar e apagar mensagens enviadas pela API, recursos úteis mas não obrigatórios para o fluxo de lembretes.
Quantos lembretes um número consegue enviar por dia?
O padrão é de até 200 mensagens por dia por número, depois dos 14 dias de aquecimento. Com dois lembretes por horário, isso cobre por volta de 100 atendimentos, antes de contar as respostas do seu sistema. Agendas maiores podem usar um número por unidade ou por profissional.
Leia também: