Bot de WhatsApp na Cloud API: quando sair da biblioteca não oficial

Quem roda um bot de WhatsApp em biblioteca não oficial conhece o argumento que adia a migração há anos: a API oficial é cara, burocrática e lenta de aprovar. Dois desses três continuam parcialmente verdadeiros. O primeiro tem data marcada para mudar de valor, e a data é 1º de outubro de 2026.

Se você ainda está escolhendo entre Baileys, Venom e whatsapp-web.js, a decisão está no comparativo das três bibliotecas. Aqui a suposição é outra: o bot já existe, roda numa biblioteca não oficial e funciona. A pergunta é quando o custo de continuar assim passa o custo de sair, o que exatamente você paga no pedágio de entrada da WhatsApp Cloud API e o que muda no deploy no dia seguinte. Tudo o que segue foi conferido na documentação da Meta em 24 de agosto de 2026, com os links para você reconferir na data em que estiver decidindo, porque esta política já mudou três vezes em pouco mais de um ano.

O que muda em 1º de outubro de 2026, e por que isso é o gatilho

Desde a virada para cobrança por mensagem, em meados de 2025, uma regra dominou toda decisão de arquitetura em cima da plataforma: responder alguém com a janela de atendimento aberta não custava nada. Bot reativo era estruturalmente barato, e era isso que puxava a conta a favor da via oficial para quem só atende.

Essa regra tem prazo. A página de preços de mensagens que não são template anuncia, com todas as letras, duas mudanças para 1º de outubro de 2026:

“Effective October 1, 2026, Meta will charge for service messages, which have not been charged since November 2024.”

“Effective October 1, 2026, Meta will charge for utility messages sent in response to users within an open 24-hour customer service window.”

Ou seja: a mensagem livre que você manda respondendo o cliente passa a ser cobrada, e o template de utilidade entregue dentro da janela perde a gratuidade que tinha desde julho de 2025. Três detalhes da mesma página completam o quadro, e cada um muda uma linha de planilha:

Não há desconto por volume em mensagem de serviço. “Meta does not offer volume tiers for service messages. Meta continues to offer volume tiers for utility and authentication messages.” Quem atende muito não fica mais barato por atender muito.
A janela de 72 horas de ponto de entrada gratuito continua de pé. “The 72-hour free entry point window is unchanged for message delivery.” Se o seu tráfego nasce de anúncio clique para WhatsApp, uma parte relevante do seu volume segue sem custo de entrega.
As tarifas ainda não são públicas. A mesma página se compromete a publicar as que passam a valer em outubro, “including rates for service messages, by September 1, 2026”.

Esse último item é o que organiza o calendário da decisão, e vale escrever de forma direta: a conta que decide a sua migração só fica completa depois de 1º de setembro, e vale a partir de 1º de outubro. Você tem cerca de trinta dias entre saber o número e ele passar a valer. Quem quiser chegar em outubro já rodando precisa fazer a parte lenta agora, com a parte cara ainda em aberto.

Vale registrar uma correção nossa, porque a fonte aqui somos nós: em 19 de agosto escrevemos que um bot reativo custa quase nada na via oficial. Era verdade naquele dia e continua sendo até 30 de setembro de 2026. A partir de outubro, “responder é de graça” deixa de ser uma característica estrutural da plataforma e vira só a descrição de um período que acabou.

E não é um movimento isolado. Desde 1º de agosto de 2026 a Meta também cobra por token as mensagens do Meta Business Agent, a US$ 2,00 por milhão de tokens, segundo a mesma página. A direção é clara: o que era gratuito para estimular adoção está sendo precificado item a item.

O cálculo que decide: custo de ficar contra custo de sair

Migração de canal quase nunca se decide comparando funcionalidades. Decide-se comparando dois riscos que não são da mesma natureza, e a maior parte das discussões trava porque as pessoas somam coisas que não somam.

O que você paga	Biblioteca não oficial	Cloud API
Risco de perder o número	Existe, sem aviso e sem prazo de recurso definido	Não por engenharia reversa; existe por qualidade e por política
Custo por mensagem	Zero	Marketing e autenticação sempre; serviço e utilidade na janela a partir de 01/10/2026
Estado para hospedar	Sessão viva, que a biblioteca reescreve sozinha	Nenhum. Token estático em variável de ambiente
Aprovação do seu texto	Nenhuma	Todo envio proativo é template aprovado por terceiro
Teto de envio	Não declarado, e o excesso é justamente o que chama atenção	Declarado, com escada previsível
Forma do serviço	Processo de instância única, conexão longa	Serviço web comum, com porta e health check

A leitura que resolve a maioria dos casos é assimétrica: do lado não oficial o custo é um evento raro e catastrófico; do lado oficial é uma despesa pequena e contínua. Ninguém troca despesa contínua por evento raro só porque a matemática do valor esperado fecha. As pessoas trocam quando o evento raro deixa de ser tolerável.

Por isso os quatro sinais abaixo pesam mais que qualquer planilha. Se dois deles são verdade hoje, a migração parou de ser opcional:

Alguém de fora depende do número. Cliente, paciente, aluno, comprador. O teste de uma frase continua o mesmo: se este número parar agora, quem liga reclamando?
Você precisa iniciar conversa. Cobrança, lembrete, confirmação, aviso de entrega. Isso é exatamente o comportamento que uma biblioteca não oficial faz por sua conta e risco, e é exatamente o que o lado oficial resolve com template.
Mais de uma pessoa ou mais de um sistema fala pelo número. Sessão única de WhatsApp Web não se compartilha bem, e a gambiarra que resolve isso costuma ser a origem do bloqueio.
Você já tomou um bloqueio, mesmo que temporário. Um susto é amostra pequena. Dois é padrão.

E o inverso também precisa ser dito, porque migrar sem motivo é desperdício: bot interno, automação pessoal, protótipo, volume baixo e número dedicado descartável continuam melhor servidos pela via não oficial. Nesse caso o guia de hospedar bot de WhatsApp 24/7 resolve o seu problema por completo, e este texto aqui é leitura de calendário, não tarefa.

O pedágio de entrada: número, verificação e nome

Aqui está a parte que quase nenhum tutorial mostra, e é onde os times perdem semanas achando que estavam a um npm install de distância.

O número. A documentação de números da Cloud API lista os requisitos: o número precisa ser seu, ter código de país e de área (“short codes are not supported”), conseguir receber ligação ou SMS e ter o que a própria página chama de “scaled capabilities”, sem explicar o termo ali. Até aí, previsível. O que pega é a frase seguinte:

“Numbers already in use with WhatsApp cannot be registered unless they are deleted first.”

Traduzindo para o seu caso concreto: o número que hoje roda o seu bot está registrado no WhatsApp, então ele não pode ser registrado na Cloud API sem antes ter a conta apagada. Não existe conversão no lugar, sem interrupção. Existe apagar de um lado e registrar do outro, com uma janela de indisponibilidade no meio. É por isso que a seção de roteiro, mais abaixo, começa mandando você não apagar nada.

A verificação de negócio. A Meta a define como “a process that allows us to gather information about you and your Business so we can verify your identity as a business entity”. Na prática ela é o que separa uma conta de teste de uma operação: a documentação de limites de mensagens lista verificar a empresa como um dos caminhos para sair do teto inicial de 250 clientes únicos por 24 horas. É um processo documental, envolve a pessoa jurídica e não é instantâneo. Comece por ele, não por último.

O nome de exibição. O nome que aparece para o cliente também passa por revisão. A API expõe isso num campo próprio, name_status, com estados como APPROVED, PENDING_REVIEW e DECLINED. Nome de exibição reprovado é um item de bloqueio silencioso: tudo funciona tecnicamente e o cliente ainda vê um número cru.

A janela de 24 horas vira estado no seu código

No lado não oficial, mandar mensagem é mandar mensagem. No lado oficial, a permissão de enviar depende de um relógio, e esse relógio é a coisa mais importante que a sua aplicação passa a controlar. A documentação de mensagens define assim:

“When a WhatsApp user messages you or calls you, a 24-hour timer called a customer service window starts. If the user messages or calls you again before the timer expires, the timer resets to 24 hours.”

Duas coisas aí costumam surpreender. A primeira é que a janela reinicia a cada nova interação do usuário, então uma conversa ativa nunca fecha a janela na prática. A segunda é que uma ligação recebida também abre e reinicia o relógio, o que não é óbvio para quem só pensa em texto.

Com a janela aberta você manda mensagem livre, o que a Meta chama de mensagem de serviço: “free-form messages that you can send to WhatsApp users during a customer service window”. Com ela fechada, a regra é curta:

“When the window closes, you can only send pre-approved template messages.”

O que isso significa em código é concreto: você passa a guardar, por contato, o instante da última mensagem recebida, e a decidir no momento do envio entre texto livre e template. É um estado novo, pequeno, mas que precisa sobreviver a redeploy, o que na prática significa um Postgres ou um Redis ao lado do serviço. Não é a sessão gigante e frágil do Baileys, é uma coluna com data.

E a partir de 1º de outubro esse mesmo ramo do código ganha uma segunda função: além de dizer o que você pode mandar, ele passa a dizer quanto custa mandar. Quem instrumentar essa decisão agora, contando quantos envios caem de cada lado, chega em setembro com a sua própria conta pronta assim que a Meta publicar as tarifas.

Templates: seu texto passa a ser revisado por terceiro

Todo envio proativo, ou seja fora da janela, é um template aprovado. A documentação de templates fixa três pontos que mudam processo de time, não só código.

Primeiro, a categoria. “Each template must be categorized as authentication, marketing, or utility”, e a mesma página avisa que “template categories also factor into pricing”. A categoria não é etiqueta organizacional: ela é o preço.

Segundo, o prazo. “Review can take up to 24 hours.” Parece pouco até você perceber que isso entra no seu ciclo de release: mudar a redação de um aviso de cobrança deixa de ser um commit e passa a ser um commit mais uma fila de aprovação externa.

Terceiro, e é o que morde depois: template tem estado, e o estado piora sozinho. A lista publicada inclui In-Review, Rejected, Active - High Quality, Active - Medium Quality, Active - Low Quality, Paused, Disabled e Appeal Requested. E a definição de Paused é explícita:

“The template has been paused due to recurring negative feedback from customers, or low read-rates.”

Traduzindo para operação: um template que vinha funcionando pode parar no meio de uma campanha por causa do comportamento de quem recebe, e você descobre isso pelo erro de envio, não por um aviso. Se o seu fluxo crítico depende de um único template, ele tem um ponto único de falha que não está no seu código nem na sua infraestrutura. Vale ter alternativa aprovada antes de precisar.

O limite de envio conta menos do que parece

A escada de limites, os degraus e as regras de promoção estão no comparativo das bibliotecas, e não vale a pena repeti-los aqui. O que muda quando o assunto é migrar, e que aquele texto não diz, é uma leitura só.

O teto não pune tamanho de operação, pune iniciativa. Duas empresas com exatamente o mesmo volume mensal podem estar uma folgada e a outra travada, e a diferença é só quem começou a conversa: quem responde não consome limite, quem aborda consome. Se o seu bot atual dispara, o limite é a primeira parede que você encontra; se ele atende, essa parede provavelmente não existe para você.

Daí a conclusão que reordena o cronograma: o teto inicial raramente é o gargalo real da migração. O gargalo são os passos 4 e 5 do roteiro mais abaixo, a aprovação de template e a verificação de negócio, porque os dois têm fila humana e nenhum dos dois acelera com esforço seu. O limite, ao contrário, se resolve sozinho enquanto você opera. É por isso que os dois disparam antes do corte de tráfego no roteiro, e não depois dele.

O deploy muda de forma: sai o worker com sessão, entra um serviço web

Esta é a parte boa, e ela é subestimada porque não aparece na conta de mensagem. O que some é a instância única. No caminho não oficial existe um processo que segura um canal aberto e carrega uma sessão que ele mesmo reescreve, e é isso que proíbe rodar duas cópias, complica o redeploy e faz você tratar um bot como se fosse um banco de dados. Do lado oficial nada disso sobra: a Meta bate no seu endereço quando chega mensagem, você responde e acabou. O bot volta a ser um serviço web sem memória própria, do mesmo feitio de um bot de Telegram ou Discord com token em variável de ambiente, com uma consequência que vale ouro em plantão: ele escala horizontalmente e reinicia sem parear de novo.

Os requisitos do endpoint estão na documentação de webhooks da Graph API, e três deles decidem escolha de hospedagem:

HTTPS com certificado válido, e nada de atalho. “Your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.” Endpoint atrás de IP com certificado autoassinado não recebe webhook, ponto.
Handshake de verificação. No cadastro, a Meta faz um GET com hub.mode, hub.verify_token e hub.challenge, e o seu endpoint precisa conferir o token e devolver o desafio.
Assinatura em toda entrega. Cada notificação vem com o cabeçalho X-Hub-Signature-256: “Generate a SHA256 signature using the payload and your app’s App Secret. Compare your signature to the signature in the X-Hub-Signature-256 header.”

Some a isso o comportamento de reentrega, que está na documentação de webhooks do WhatsApp: se o seu endpoint não devolve 200, “Meta retries delivery with decreasing frequency until the request succeeds, for up to 7 days”, e o payload pode ter até 3 MB. Reentrega por sete dias é ótimo para não perder mensagem e péssimo se o seu processamento não for idempotente: sem deduplicação por identificador de mensagem, um deploy ruim vira cliente recebendo a mesma resposta várias vezes.

O esqueleto inteiro cabe em poucas linhas, e a ordem importa: valide, responda, processe depois.

import express from 'express'
import crypto from 'node:crypto'

const app = express()
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf } }))

// Verificação: a Meta chama uma vez, no cadastro do webhook.
app.get('/webhook', (req, res) => {
  const modo = req.query['hub.mode']
  const token = req.query['hub.verify_token']
  if (modo === 'subscribe' && token === process.env.VERIFY_TOKEN) {
    return res.status(200).send(req.query['hub.challenge'])
  }
  return res.sendStatus(403)
})

// Recebimento: confira a assinatura, devolva 200 e só então processe.
app.post('/webhook', (req, res) => {
  const recebida = req.get('x-hub-signature-256') ?? ''
  const esperada =
    'sha256=' +
    crypto.createHmac('sha256', process.env.APP_SECRET).update(req.rawBody).digest('hex')

  const confere =
    recebida.length === esperada.length &&
    crypto.timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada))

  if (!confere) return res.sendStatus(401)

  res.sendStatus(200)
  enfileirar(req.body) // idempotente por id de mensagem
})

app.get('/health', (_req, res) => res.sendStatus(200))
app.listen(process.env.PORT || 3000, '0.0.0.0')

Na Upuai isso sobe por git push, sem Dockerfile e sem YAML, porque não há navegador para instalar: é um app Node comum. O certificado que a Meta exige é o mesmo ponto em que muita gente trava, e ele já vem resolvido, porque domínio customizado sai com certificado automático, emitido e renovado sem você tocar. O health check do exemplo se declara no repositório, versionado junto do código:

#:schema https://upuai.com.br/schemas/upuai-toml-v1.json
[deploy]
healthCheckPath = "/health"

E a diferença de tamanho em relação ao caminho com navegador é grande. Um webhook é a forma mais econômica das três: um serviço nasce com 0,5 vCPU e 512 MB no período de teste e 1 vCPU e 1 GB no Starter, tamanho em que um Chromium do Venom ou do whatsapp-web.js já vive apertado (é o motivo de aquele caminho pedir o deploy com Dockerfile e um plano maior), enquanto um serviço que valida assinatura, devolve 200 e enfileira cabe ali com folga. Duas honestidades no mesmo parágrafo, porque elas mudam a sua escolha de plano: o período de teste guarda log por 12 horas (24 no Starter, 48 no Plus, 72 no Pro), e depurar assinatura de webhook é exatamente o tipo de coisa que você vai investigar no dia seguinte; e o período de teste não tem backup automático de banco, então a tabela que guarda a janela de 24 horas de cada contato pede plano pago assim que virar operação de verdade.

O roteiro de corte sem perder o número

A ordem abaixo existe para você nunca ficar sem canal. O erro clássico é começar apagando.

Não apague nada ainda. O número atual continua rodando na biblioteca não oficial até o fim deste roteiro.
Consiga um número novo, que nunca teve WhatsApp, para o piloto. É a única forma de testar sem derrubar o que está no ar.
Abra o portfólio de negócios e o app, registre o número novo e aponte o webhook. Aqui você já valida o handshake, a assinatura e a idempotência com tráfego real de teste.
Submeta os templates que você sabe que vai precisar. A revisão leva até 24 horas por template, e você não quer descobrir isso na véspera.
Inicie a verificação de negócio em paralelo. É o processo com fila mais longa e o que destrava o teto de 250.
Rode os dois em paralelo por algumas semanas. Biblioteca não oficial no número antigo, Cloud API no número novo, com o mesmo código de negócio atrás dos dois se der.
Só então decida o destino do número antigo. Duas saídas legítimas: divulgar o número novo e aposentar o antigo devagar, ou migrar o antigo de fato. Se for migrar, avise os clientes antes, apague a conta de WhatsApp dele e registre na Cloud API sabendo que existe uma janela de indisponibilidade e ela não é evitável.
Guarde a contagem. Quantos envios caíram dentro e quantos fora da janela, por dia. Em setembro, quando as tarifas de outubro saírem, essa planilha vira a sua decisão em cinco minutos.

Perguntas frequentes

Preciso apagar o número atual do WhatsApp para usá-lo na Cloud API?

Sim. A documentação da Meta é direta: números já em uso no WhatsApp não podem ser registrados a menos que sejam apagados antes. Não existe conversão no lugar e não existe migração sem interrupção para o mesmo número. É por isso que o piloto se faz com um número novo, e a decisão sobre o número antigo vem por último.

O que exatamente encarece em 1º de outubro de 2026?

Duas coisas que hoje são gratuitas: a mensagem livre que você manda dentro da janela de 24 horas (a mensagem de serviço) e o template de utilidade entregue dentro dessa mesma janela. Marketing e autenticação já eram cobrados e continuam. A janela de 72 horas de ponto de entrada gratuito, aberta por anúncio clique para WhatsApp, segue sem custo de entrega. As tarifas serão publicadas pela Meta até 1º de setembro de 2026.

Dá para operar sem verificar a empresa?

Dá para começar, não dá para escalar. Sem verificação você fica no teto inicial de 250 clientes únicos por 24 horas contados fora da janela de atendimento. Para um bot que só responde, isso pode durar bastante. Para qualquer coisa que dispare mensagem, o teto chega rápido, e a verificação é justamente um dos caminhos de saída dele.

Meu webhook pode ficar num IP com certificado autoassinado?

Não. A exigência da Meta é certificado TLS ou SSL válido e corretamente instalado, e a documentação diz textualmente que certificado autoassinado não é suportado. Na prática isso significa domínio com certificado emitido por autoridade reconhecida. É o requisito de infraestrutura mais concreto de toda a migração e o que mais reprova endpoint improvisado.

Vale esperar a publicação das tarifas para decidir?

Vale esperar para decidir volume, não para começar. A parte lenta da migração (verificação de negócio, aprovação de template, ajuste do código para a janela de 24 horas) não depende de preço nenhum e leva semanas. Quem começa em setembro chega em outubro com o número publicado e nada rodando. Quem começa agora chega com o piloto no ar e só precisa decidir quanto do tráfego move.

Decida pela data, não pelo humor

A migração para a API oficial nunca teve prazo, e é por isso que ela vive sendo adiada. Agora tem: 1º de setembro de 2026 você descobre o preço, 1º de outubro ele passa a valer, e o que fica caro é exatamente a parte que era o melhor argumento a favor da via oficial para quem só atende. Isso não torna a biblioteca não oficial mais segura, ela continua exatamente onde estava, com o mesmo risco de perder o número sem aviso. Torna a decisão datável, e decisão datável é a única que sai do papel.

O trabalho pesado desta migração é fila de aprovação, e fila de aprovação não acelera com dinheiro nem com stack melhor. O que dá para acelerar é o pedaço técnico: subir o webhook, validar a assinatura, medir quantos envios caem dentro e fora da janela, e chegar em setembro com dado próprio em vez de estimativa.

Esse piloto cabe inteiro nos 15 dias de teste, sem cartão; pra manter no ar depois, o plano Starter custa R$ 19/mês. Comece seus 15 dias grátis, suba o serviço por git push, aponte um domínio com certificado automático e deixe rodando ao lado do bot atual pelas próximas semanas. Quando o piloto virar operação, a fatura vem em Real, sem conversão de moeda e sem IOF, com a infraestrutura no Brasil: os planos e limites estão em upuai.com.br/pricing. E se além de trocar de canal você também está saindo de uma plataforma internacional, vale ler a mesma decisão pelo lado da hospedagem em alternativa ao Railway no Brasil.