Quem pede informação sobre uma vaga decide em poucos dias, e decide com quem respondeu. Com a API do zapon, o site, o formulário da feira ou o sistema de gestão escolar disparam o retorno na hora, agendam a visita, mandam o lembrete e recebem a resposta do responsável por webhook — sem alguém da secretaria segurando o celular.
A escola perde matrícula em dois pontos previsíveis. O primeiro é o silêncio depois do pedido de informação: a família preencheu o formulário às 21h de terça, a secretaria abre às 8h de quarta, e até o retorno sair a mãe já visitou duas escolas. O segundo é o interessado que visitou e sumiu, porque a retomada dependia de um bilhete no bloco da coordenação.
Os dois buracos têm a mesma causa: a comunicação depende de alguém lembrar. Uma API de WhatsApp transfere esse lembrar para o sistema. O zapon expõe uma API REST direta — header token, JSON entrando e saindo — que o seu site, o seu CRM de captação ou a sua ferramenta de automação chamam como chamariam qualquer serviço. Abaixo: o fluxo do interessado até a rematrícula, os endpoints em cURL e Node, e o evento que chega quando o responsável responde.
Porque na hora em que ele pediu havia interesse, e na hora em que a secretaria retornou já havia outra escola na frente. Decisão de escola se toma em conversa de família, num intervalo curto: quem responde em minutos entra na conversa, quem responde no dia seguinte entra na lista de "a gente já viu". Um retorno automático que diz o curso e o período consultados e propõe uma visita mantém a escola dentro da janela em que a decisão está aberta.
São três vazamentos, e cada um pede uma mensagem diferente:
Porque a captação é sazonal e o quadro da secretaria não é. Em outubro a mesma pessoa atende o balcão, emite declaração de vaga, organiza a rematrícula e ainda deveria ligar para os interessados da semana. Ligação não escala e não deixa rastro. A mensagem, além de chegar, volta como um evento com telefone, horário e conteúdo — que o sistema grava no cadastro do interessado.
Três coisas: um número de WhatsApp que a escola controla, uma conta no zapon com esse número conectado por QR Code ou código de pareamento, e alguma origem de dados que saiba quem pediu informação e quem tem visita marcada — o sistema de gestão escolar, o CRM de captação ou até a planilha do formulário do site. Não é preciso servidor próprio, conta na Meta, aprovação de template nem aplicativo instalado no celular da secretaria.
token, credencial de todas as chamadas daquele número. Escola com duas unidades costuma querer uma conexão por unidade — a mensagem sai do número certo só trocando o header.Se ele permite chamada HTTP, sim: uma requisição quando o interessado entra, outra quando a visita é marcada e uma rotina diária que varre o dia seguinte. Se é fechado, leia os dados por fora — exportação, relatório, banco — e dispare de uma camada intermediária. A API não precisa conhecer o seu modelo de dados; ela recebe telefone e texto.
Cinco etapas: (1) o interessado pede informação e recebe o retorno na hora, já dizendo qual curso e qual período ele consultou; (2) uma pergunta curta com botões qualifica série ou turno; (3) o sistema oferece a visita à escola ou a aula experimental com dia, hora e o que trazer; (4) na véspera sai o lembrete, e a resposta volta por webhook; (5) depois da visita, a retomada lista os documentos que faltam e envia o contrato ou a lista de material em PDF. O que sai do previsto vai para a secretaria.
Cada passo tem um objetivo distinto. Repetir a mesma mensagem cinco vezes é a forma mais rápida de o responsável silenciar a conversa.
A primeira mensagem prova que há alguém do outro lado e devolve o que a pessoa consultou. Se ela olhou o 6º ano no período da manhã, a mensagem diz "6º ano, manhã": genérico soa como robô, específico soa como atendimento. Conteúdo mínimo: nome da escola, curso e período consultados, uma linha sobre o que a escola oferece naquele segmento e uma pergunta de resposta curta. Este envio também valida o canal — se falhar aqui, você descobre hoje que o formulário capturou um telefone errado, não na semana da matrícula.
Uma pergunta, três ou quatro botões, rótulo curto. Série pretendida ou turno resolve o roteamento interno: o infantil vai para uma coordenação, o pré-vestibular para outra, e o curso livre nem passa pela mesma secretaria. Resista a perguntar renda, profissão e escola anterior por mensagem — isso é conversa de visita, e cada pergunta a mais derruba a resposta. O identificador do botão carrega o número do interessado no cadastro, então a resposta chega amarrada ao registro certo.
Assim que a qualificação volta, ofereça data e hora concretas. "Quando você pode vir?" devolve a decisão para quem não conhece a agenda da escola; "quinta às 9h ou sexta às 14h" fecha. A confirmação precisa ter data, dia da semana, horário, endereço com ponto de referência, quem vai receber e o que trazer — se a aula experimental pede uniforme ou material, isso está no texto. Guarde o Id devolvido pela API junto do agendamento: é ele que prova qual mensagem saiu.
Na véspera, uma rotina varre as visitas e aulas experimentais do dia seguinte e dispara um lembrete curto pedindo confirmação; a resposta volta por webhook e atualiza a agenda da coordenação. Aqui está a diferença que organiza a operação inteira: com quem visitou, a escola está oferecendo uma vaga, e a régua é curta, com data para acabar. Com quem já é aluno, a escola presta um serviço contratado, e a régua vira o calendário letivo — reunião de pais, entrega do boletim, período de rematrícula, vencimento da mensalidade. Dois fluxos, duas listas, dois tons; misturá-los faz o responsável de um aluno do 9º ano receber convite para conhecer a escola.
Depois da visita, a retomada não pergunta "e aí, o que você achou?". Ela nomeia o que falta: histórico escolar da escola anterior, certidão de nascimento, comprovante de endereço, assinatura do responsável financeiro no contrato. Documento nomeado item a item é documento que chega. É aqui também que entram os anexos — contrato de matrícula ou lista de material didático em PDF, no mesmo canal em que a conversa acontece. E quando o responsável foge do roteiro — desconto, bolsa, segunda via —, a conversa vira pendência da secretaria, com nome e telefone, não um evento perdido.
Quatro resolvem o fluxo inteiro: POST /chat/send/text para as mensagens, POST /chat/send/buttons para a qualificação e a confirmação em um toque, POST /chat/send/document para mandar o contrato ou a lista de material em PDF, e POST /user/check para conferir quais telefones do cadastro têm WhatsApp. Todos usam a base https://api.zapon.dev e o header token. São 49 endpoints publicados — 23 de /chat, 18 de /group e 8 de /user —, mas a captação vive nesses quatro.
A autenticação é um header só, token, copiado da conexão no painel: não é Authorization, não é Bearer, não há OAuth. Trate-o como a senha do sistema acadêmico — quem tem o token envia em nome da escola.
Um POST em /chat/send/text com dois campos obrigatórios: Phone, o número em formato internacional só com dígitos, e Body, o texto.
curl -X POST https://api.zapon.dev/chat/send/text \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Body": "Olá, Cláudia! Aqui é da secretaria do Colégio Exemplo.\n\nVocê consultou vaga para o 6º ano, período da manhã. Temos turmas de 25 alunos e o material didático já incluso na mensalidade.\n\nQuer conhecer a escola? Consigo quinta às 9h ou sexta às 14h." }'
A resposta traz o identificador da mensagem no WhatsApp:
{
"code": 200,
"success": true,
"data": {
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2026-03-01T09:12:08-03:00"
}
}Grave esse Id no cadastro do interessado: ele diz qual mensagem saiu e impede que uma rotina reprocessada mande o mesmo retorno de novo.
O /chat/send/buttons envia botões de resposta rápida. Cada um carrega um id definido por você, e é ele que volta no webhook quando o responsável toca. Coloque o número do interessado aí dentro: a resposta chega amarrada ao registro sem interpretar texto. Além da resposta rápida, o mesmo endpoint monta botão que abre um link ("type": "cta_url"), botão que abre o discador ("type": "cta_call") e botão que copia um código ("type": "copy") — e os tipos convivem na mesma mensagem. O toque em resposta rápida volta no webhook; os outros três agem no aparelho de quem recebe.
POST https://api.zapon.dev/chat/send/buttons token: SEU_TOKEN { "Phone": "5511999999999", "Body": "Para eu separar a turma certa: em qual período você pensa para o 6º ano?", "Footer": "Colégio Exemplo — secretaria", "Buttons": [ { "id": "int9034|manha", "text": "Manhã" }, { "id": "int9034|tarde", "text": "Tarde" }, { "id": "int9034|integral", "text": "Integral" } ] }
O rótulo é curto por natureza do WhatsApp — uma ou duas palavras, até vinte caracteres. Se as opções forem muitas, como escolher entre seis horários de aula experimental, o /chat/send/list entrega um menu em lista. Aceite texto também: quem escreve "de manhã" precisa ser entendido.
O padrão é uma rotina agendada — um cron no fim da tarde — que busca as visitas e aulas experimentais do dia seguinte, monta o texto e chama a API. Em Node:
// visitas.js — roda todo dia às 17h const API = "https://api.zapon.dev"; const TOKEN = process.env.ZAPON_TOKEN; async function enviarTexto(phone, body) { const r = await fetch(`${API}/chat/send/text`, { method: "POST", headers: { "token": TOKEN, "Content-Type": "application/json" }, body: JSON.stringify({ Phone: phone, Body: body }) }); const json = await r.json(); if (!r.ok || !json.success) throw new Error(json.error || `HTTP ${r.status}`); return json.data.Id; } const pausa = (ms) => new Promise((r) => setTimeout(r, ms)); for (const v of await visitasDeAmanha()) { if (v.situacao !== "agendada" || v.responsavel.semContato) continue; try { const id = await enviarTexto(v.responsavel.telefone, `${v.responsavel.nome}, sua visita ao Colégio Exemplo é amanhã, ${v.data}, às ${v.hora}.\n\n` + `Quem recebe vocês é a ${v.coordenacao}. Traga um documento com foto; ` + `se o ${v.aluno} for fazer a aula experimental, leve caderno e estojo.\n\n` + `Confirma para mim? Responda 1 para sim ou 2 para remarcar.`); await registrarEnvio(v.id, "lembrete_visita", id); // guarda o Id: não duplica } catch (e) { await registrarFalha(v.id, "lembrete_visita", String(e)); // vira tarefa da secretaria } await pausa(4000); // não despeje a lista inteira no mesmo segundo }
Três detalhes desse laço separam a rotina que dura da que quebra na primeira semana de captação. O continue impede lembrete de visita cancelada e de quem pediu para não receber. O registrarEnvio guarda o Id, então rodar a rotina duas vezes não manda duas mensagens. E a pausa evita transformar a lista numa rajada de centenas de envios no mesmo instante, comportamento que não se parece com o de uma secretaria.
O /chat/send/document recebe o arquivo em data URI base64, o nome com que ele aparece no celular e uma legenda opcional. O FileName importa: é por ele que a família vai procurar o arquivo em fevereiro, na hora de comprar o material.
curl -X POST https://api.zapon.dev/chat/send/document \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Document": "data:application/pdf;base64,JVBERi0xLjQKJcfs…", "FileName": "lista-material-6ano-2027.pdf", "Caption": "Cláudia, segue a lista de material do 6º ano para 2027. O contrato de matrícula vai em seguida, para assinatura do responsável financeiro." }'
O PDF é documento oficial: gere o arquivo a partir do sistema, com o ano letivo no nome, em vez de reaproveitar o do ano passado renomeado.
Cadastro de responsável envelhece rápido: o telefone entrou na matrícula do 1º ano e a família trocou de número duas vezes desde então. Antes da régua de rematrícula, passe a base pelo POST /user/check, que recebe uma lista e diz quais números têm conta no WhatsApp.
curl -X POST https://api.zapon.dev/user/check \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": ["5511999999999", "5511888888888"] }' // retorno { "code": 200, "success": true, "data": { "Users": [ { "Query": "5511999999999", "IsInWhatsapp": true, "JID": "[email protected]" }, { "Query": "5511888888888", "IsInWhatsapp": false, "JID": "" } ] } }
O que voltar como false não é para insistir: vira lista para a atualização cadastral do ano letivo seguinte. Ao todo são 13 formas de envio — texto, imagem, áudio, vídeo, documento, sticker, localização, contato, enquete, lista, botões, template e edição de mensagem já enviada —, mais reação, presença, marcar como lido e histórico. Fora dos quatro do fluxo, os úteis para escola são localização, no lembrete da visita, e imagem, para a foto do laboratório.
Cada conexão tem o seu webhook: você cadastra no painel a URL do seu sistema e escolhe os eventos. A partir daí, toda mensagem recebida naquele número é entregue como um POST nessa URL, com o conteúdo inteiro no corpo — telefone, identificador, horário, texto e, quando é toque em botão, o id que você definiu. Não há nada para ficar consultando de tempos em tempos.
O ciclo tem três partes que não se misturam: o webhook entrega o evento, a sua regra interpreta e a ação acontece no seu sistema. A API não sabe o que é uma aula experimental; sabe que uma mensagem chegou de um número.
O corpo traz o tipo do evento e a mensagem inteira. Assim chega quem respondeu "1" ao lembrete da visita:
{
"type": "Message",
"event": {
"Info": {
"ID": "3EB0C767D26A1B5F7C83",
"Chat": "[email protected]",
"Sender": "[email protected]",
"IsFromMe": false, "IsGroup": false,
"PushName": "Cláudia Menezes",
"Timestamp": "2026-03-11T18:04:22-03:00"
},
"Message": { "conversation": "1" }
}
}
// quando ela toca num botão, muda só o bloco Message:
"Message": { "buttonsResponseMessage": {
"selectedButtonID": "int9034|manha",
"Response": { "SelectedDisplayText": "Manhã" }
} }Duas observações economizam horas de depuração. O corpo pode chegar como JSON puro ou como formulário codificado com o JSON dentro de um campo — aceite os dois. E o que o próprio número da escola envia também gera evento, com IsFromMe igual a true: ignore, ou a secretaria respondendo uma família vai disparar a sua automação.
Descarte o que não interessa, encontre o registro, decida pela intenção e responda confirmando o que foi feito — é essa última parte que evita o "respondi e não sei se chegou".
app.post("/secretaria/whatsapp", express.json(), async (req, res) => { res.sendStatus(200); // responda primeiro, processe depois const ev = req.body?.event ?? req.body, info = ev?.Info ?? {}; if (info.IsFromMe || info.IsGroup) return; // o que a escola enviou, e grupos, fora if (await jaProcessado(info.ID)) return; // o mesmo evento pode chegar 2x const telefone = String(info.Chat || "").split("@")[0]; const botao = ev?.Message?.buttonsResponseMessage?.selectedButtonID ?? ""; const texto = (ev?.Message?.conversation ?? ev?.Message?.extendedTextMessage?.text ?? "").trim().toLowerCase(); const reg = botao ? await buscarInteressado(botao.split("|")[0]) : await interessadoPorTelefone(telefone); if (!reg) return filaDaSecretaria(telefone, texto); if (botao) { // qualificação de turno await definirPeriodo(reg.id, botao.split("|")[1]); return ofertarHorariosDeVisita(reg); } if (/^(1|sim|confirmo|confirmado)$/.test(texto)) { await confirmarVisita(reg.visitaId); return enviarTexto(telefone, `Combinado. Até amanhã às ${reg.hora}, na portaria da Rua Exemplo, 300.`); } if (/^(2|remarcar|outro dia)$/.test(texto)) { await marcarParaRemarcar(reg.visitaId); return enviarTexto(telefone, "Sem problema. A secretaria te chama hoje com outros horários."); } return filaDaSecretaria(telefone, texto); // o resto é assunto de gente });
Ele vai escrever, e o assunto raramente é o que a automação esperava: "tem bolsa para irmão?", "vocês aceitam matrícula no meio do ano?", "meu filho tem laudo, como funciona o apoio?". Não tente responder tudo por regra. O que a automação não reconhece vira pendência com nome, telefone e o texto recebido, numa lista que a secretaria abre todo dia. A conversa continua no WhatsApp da escola, e uma pessoa responde no próprio aplicativo, como sempre respondeu. Automatize o previsível — aviso, agendamento, lembrete, documento —; deixe negociação, dúvida pedagógica e caso particular com quem tem competência para tratar.
Para o do responsável — e isso precisa estar resolvido no cadastro, não no critério de quem dispara. Aviso escolar sobre aluno menor vai para quem responde por ele: o responsável pedagógico nos assuntos de rotina e acompanhamento, o responsável financeiro nos assuntos de mensalidade e contrato. O telefone do aluno, quando existe no cadastro, serve para o que é dele, como aviso de turma no curso livre ou no pré-vestibular de maiores.
Escola é o setor em que o destinatário certo não é óbvio, porque quase nunca é a pessoa de quem a mensagem fala. Três campos separados resolvem quase tudo: telefone do responsável pedagógico, telefone do responsável financeiro e telefone do aluno. Sem essa separação, a régua de mensalidade chega para o pai que não cuida do pagamento, o boletim vai para o celular do adolescente e o convite da reunião de pais some. Se a família é separada e há dois responsáveis, o cadastro precisa comportar os dois — e a sua rotina precisa escolher qual dos dois recebe cada tipo de aviso, em vez de mandar para o primeiro da lista.
Conteúdo pedagógico ou financeiro sensível não vai no corpo da mensagem: nota baixa, reprovação, ocorrência disciplinar, laudo, encaminhamento para apoio especializado e situação de inadimplência. A mensagem avisa que existe um assunto e chama para a conversa certa — "a coordenação gostaria de conversar sobre o acompanhamento do Pedro; podemos marcar quinta às 15h?" —, sem descrever o assunto. A razão é prática: a notificação aparece na tela de bloqueio, e o celular do responsável circula pela casa, pelo trabalho e pela mão do próprio aluno. O que serve para o aviso é o mínimo: nome do aluno, turma, data, hora, local e o que fazer.
Quem tem acesso ao aparelho e aos dispositivos conectados àquele número. Isso merece o mesmo cuidado que se dá à senha do sistema acadêmico: bloqueio de tela, aparelho institucional em vez de celular pessoal, e retirada dos dispositivos conectados quando alguém deixa a equipe — professor que sai no meio do ano não pode continuar vendo a conversa das famílias. Vale também decidir antes quem responde o quê: secretaria trata matrícula, documento e mensalidade; coordenação trata acompanhamento do aluno. E o texto que o seu sistema armazenar do webhook passa a fazer parte do que a escola precisa proteger.
Não da mesma forma. Comunicação sobre a matrícula que a própria família iniciou, ou sobre o aluno que a escola já atende, é esperada: é o serviço em andamento. Divulgação de vestibulinho, campanha de bolsa, feira de profissões e evento aberto é marketing, e marketing pede consentimento explícito, registrado com data e com um caminho fácil de descadastro. Misturar os dois no mesmo disparo é o erro que transforma o número da escola num número silenciado por metade das famílias.
semContato do exemplo em Node fez. Numa família com três filhos matriculados, o pedido vale para o responsável, não para uma matrícula só.R$ 27 por mês por número conectado, sem cobrança por mensagem: o valor não muda entre um mês parado de julho e a semana de rematrícula. O que entra no planejamento é a cota de 300 mensagens por dia por número — cerca de 9.000 por mês —, então numa semana cheia vale distribuir os avisos ao longo dos dias, que é justamente o que evita o bloqueio do número. O teste é de 14 dias sem cartão e a contagem só começa na primeira conexão — dá para criar a conta, escrever a integração com o sistema de gestão com calma e só depois conectar o número.
Essa previsibilidade é o que torna o fluxo viável para escola pequena. A comunicação escolar é concentrada: quatro entregas de boletim, duas reuniões de pais, um período de rematrícula e a captação do segundo semestre. Com cobrança por mensagem, o custo estouraria justamente nos meses que importam, e alguém cortaria o lembrete para economizar. Com mais de uma unidade, é uma conexão por unidade — e o seu sistema escolhe de qual número a mensagem sai trocando o header token.
O painel mostra o estado de cada conexão e atualiza a cada 10 segundos enquanto a página está aberta. Para não depender de alguém olhando a tela, assine os eventos de conexão no webhook: Disconnected avisa a queda e LoggedOut avisa que o número precisa ler o QR Code de novo. E toda falha de envio precisa cair numa lista visível — foi o papel do registrarFalha no exemplo — que alguém da secretaria abre todo dia. Lembrete que não saiu tem que virar tarefa, não silêncio.
Funciona sempre que esse sistema conseguir fazer uma chamada HTTP ou exportar os dados de que a rotina precisa: interessados do dia, visitas agendadas, turmas, pendências de documento. Se ele tem área de integrações, chama a API direto. Se é fechado, leia por fora — relatório, exportação, banco — e dispare de uma camada intermediária com uma ferramenta de automação no meio.
Um por unidade quando as unidades têm secretarias separadas, porque quem responde é diferente e o endereço da mensagem também. Separar por segmento — infantil, fundamental, pré-vestibular — só compensa quando o time de captação é outro; caso contrário, o responsável de dois filhos passa a conversar com dois números da mesma escola. Cada conexão é um número e tem o seu token.
Resolvendo no cadastro, não no disparo: campos separados para responsável pedagógico, responsável financeiro e aluno, e uma regra que diz qual tipo de aviso vai para qual campo. Antes das réguas do ano letivo, passe a base pelo POST /user/check para separar os números que não têm mais WhatsApp e mandar essa lista para a atualização cadastral.
Dá, com a rotina percorrendo a lista da turma e uma pausa entre os envios, nunca tudo no mesmo segundo. Duas condições: o envio é individual para cada responsável, com o nome do aluno e da turma no texto, e o assunto é operacional — reunião, calendário, boletim disponível. Convite de evento aberto e campanha entram na regra de consentimento, não nessa.
R$ 27 por mês por número conectado, sem cobrança por mensagem, com cota de 300 mensagens por dia para cada número — cerca de 9.000 por mês. É essa cota que segura o ritmo de envio e mantém o número da secretaria longe do bloqueio. O teste é de 14 dias sem cartão e só começa a contar quando você conecta o primeiro número.
Pode — em qualquer API, inclusive na oficial da Meta. O risco não é eliminável, é gerenciável: fale com quem pediu contato ou já é da comunidade escolar, mantenha volume e ritmo compatíveis com o tamanho da escola e pare de enviar para quem pediu para sair. O que dispara bloqueio é mensagem não solicitada em massa, não o uso de API.
Dá, pelo POST /chat/send/document: o arquivo vai em data URI base64, com FileName e uma legenda opcional. Use um nome que a família consiga achar depois, com ano letivo e série, e gere o PDF a partir do sistema em vez de reaproveitar o arquivo do ano anterior.
A automação não responde. Nota, ocorrência, laudo e acompanhamento pedagógico saem da régua e viram pendência para a coordenação, que trata na conversa ou marca um horário. A mensagem automática, no máximo, avisa que a coordenação vai chamar — nunca traz o conteúdo pedagógico no texto.
14 dias grátis, sem cartão — a contagem só começa quando você conectar o número. Crie a conta, leia o QR Code e responda o próximo interessado no mesmo minuto.