Criar conta
← Blog

·

Como migrar de uma API não oficial (Evolution API, Baileys, WPPConnect) para a API oficial do WhatsApp

Atualizado em 20/10/2026

Migrar para a API oficial do WhatsApp significa trocar a sessão do WhatsApp Web, aberta por QR Code, por um número registrado na Cloud API da Meta, acessado com token e chamadas HTTP. O número precisa sair do app (ou ser conectado por coexistência, se estiver no app WhatsApp Business), as mensagens fora da janela de 24 horas passam a exigir templates aprovados, e o formato dos webhooks muda para o padrão da Meta. O trabalho maior costuma estar no código de recebimento de eventos e nas regras de envio, não no envio em si.

Este guia é para quem tem uma integração rodando com Baileys, WPPConnect ou o modo Baileys da Evolution API e quer ir para a API oficial sem parar a operação.

Por que migrar: o risco real das APIs não oficiais

Bibliotecas não oficiais controlam uma sessão do WhatsApp Web. Para o WhatsApp, isso é acesso automatizado não autorizado. Os Termos de Serviço proíbem acessar ou usar o serviço “por meios automatizados” sem autorização e listam envio em massa e mensagens automáticas entre os usos não permitidos.

As consequências são conhecidas por quem já operou nesse modelo:

  • Banimento do número, às vezes sem relação clara com volume. Um número banido precisa passar por apelação antes de poder ser registrado de novo, inclusive na Cloud API, conforme a documentação de números.
  • Quebras após atualizações do WhatsApp, que exigem atualizar a biblioteca às pressas.
  • Sessões que caem e precisam de nova leitura de QR Code, muitas vezes por alguém com o celular na mão.
  • Nenhum suporte da Meta quando algo dá errado.

Na API oficial, o banimento por “usar a ferramenta errada” deixa de existir. O que passa a importar é a qualidade: bloqueios e denúncias dos destinatários afetam a classificação do número e os limites de envio.

O que muda ao migrar

AspectoAPI não oficialAPI oficial (Cloud API)
ConexãoQR Code e sessão persistida no servidorToken de acesso; número registrado na Meta
Envio fora de conversa ativaMensagem livreSomente template aprovado
Resposta ao clienteLivre, a qualquer momentoLivre dentro da janela de 24 h; depois, template
Identificador do contatoJID (5584999999999@s.whatsapp.net)wa_id (5584999999999)
Identificador da mensagemID da bibliotecawamid.…
EventosFormato próprio (ex.: messages.upsert)Webhook da Meta: entry[].changes[].value
Mídia recebidaArquivo ou base64 no eventomedia_id; o arquivo é baixado por outra chamada
GruposAmplo acessoAPI de Grupos com limites (8 participantes, exige conta comercial oficial)
CustoSem cobrança da MetaCobrança por mensagem entregue

Os limites da API de Grupos estão na documentação de grupos da Meta. Se o seu fluxo depende de grupos grandes, de listas de transmissão ou de ler status de contatos, revise esse ponto antes de qualquer outra coisa, porque a API oficial não replica esses usos.

Passo a passo da migração

1. Faça o inventário do que a integração atual faz

Liste cada fluxo e classifique:

  • Resposta a mensagem do cliente (atendimento, chatbot): continua igual, dentro da janela de 24 horas.
  • Mensagem iniciada pela empresa (lembrete, cobrança, aviso de entrega, campanha): vira template.
  • Recursos sem equivalente (grupos grandes, listas de transmissão, status): precisam de outra solução.

Essa lista vira a sua lista de templates e mostra onde o produto vai mudar.

2. Prepare a conta na Meta

Você precisa de um portfólio empresarial (antigo Business Manager), de preferência verificado, e de uma forma de pagamento. A verificação influencia os limites de mensagens: portfólios novos começam com 250 destinatários únicos por 24 horas fora da janela, e a verificação é um dos caminhos para chegar a 2.000. O guia completo da API oficial detalha os requisitos.

3. Decida o que fazer com o número

Este é o ponto mais sensível. Há três caminhos:

  1. Número no app WhatsApp Business: dá para conectar à API e continuar usando o app, pela coexistência. Veja requisitos e limitações em Coexistência no WhatsApp.
  2. Número no WhatsApp comum (Messenger): é preciso excluir a conta do app antes de registrar o número na Cloud API. O histórico do aparelho não vai para a API.
  3. Número novo: permite migrar em paralelo. Você sobe o número oficial, migra os fluxos aos poucos e desliga o antigo depois.

Se o número atual já foi banido, ele só pode ser registrado depois de reativado pelo processo de apelação.

Ao desconectar a sessão não oficial, encerre a biblioteca antes de registrar o número na Meta. Duas conexões tentando usar o mesmo número geram erros difíceis de diagnosticar.

4. Crie e aprove os templates

Para cada mensagem iniciada pela empresa, crie um template com categoria correta: utilidade para avisos ligados a uma transação ou conta, autenticação para códigos, marketing para promoções. A Meta revisa e pode recategorizar. Na Vectalk, a criação usa o endpoint de templates com token de instância:

{
  "name": "lembrete_consulta",
  "language": "pt_BR",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Olá {{1}}, sua consulta está marcada para {{2}}. Responda 1 para confirmar.",
      "example": { "body_text": [["Maria", "22/10 às 14h"]] }
    }
  ]
}

O template fica com status PENDING até a aprovação. Comece por aqui, porque é a etapa que depende de terceiros.

5. Troque a camada de envio

Na API não oficial, o envio é uma chamada de função da biblioteca. Na oficial, é um POST HTTP. Um envio típico com Baileys:

// Antes (Baileys)
await sock.sendMessage('5584999999999@s.whatsapp.net', { text: 'Pedido confirmado' })

Passa a ser:

// Depois (API oficial via Vectalk)
const res = await fetch('https://apis.vectalk.com.br/api/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VECTALK_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messaging_product: 'whatsapp',
    to: '5584999999999',
    type: 'text',
    text: { body: 'Pedido confirmado' },
  }),
})
const data = await res.json()
const wamid = data.messages[0].id // guarde para cruzar com os status

O número vai no formato E.164 sem o +. Guarde o wa_id que a API devolve em contacts[0].wa_id e use esse valor como chave do contato, em vez de reconstruir o número a partir do que o usuário digitou.

Antes de enviar uma mensagem livre, o código precisa saber se a janela de 24 horas está aberta. Uma forma simples é registrar o horário da última mensagem recebida de cada contato:

function janelaAberta(ultimaMensagemDoCliente) {
  const VINTE_E_QUATRO_HORAS = 24 * 60 * 60 * 1000
  return Date.now() - ultimaMensagemDoCliente.getTime() < VINTE_E_QUATRO_HORAS
}

const payload = janelaAberta(contato.ultimaMensagemEm)
  ? { type: 'text', text: { body: texto } }
  : { type: 'template', template: { name: 'retomar_atendimento', language: { code: 'pt_BR' } } }

6. Reescreva o recebimento de eventos (webhooks)

É aqui que costuma estar a maior parte do trabalho. Em vez de eventos como messages.upsert, você recebe um POST com a estrutura da Meta, em que mensagens e status chegam dentro de entry[].changes[].value:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "558430000000", "phone_number_id": "PHONE_NUMBER_ID" },
        "contacts": [{ "profile": { "name": "João" }, "wa_id": "5584988888888" }],
        "messages": [{
          "from": "5584988888888",
          "id": "wamid.HBgL...",
          "timestamp": "1760000000",
          "type": "text",
          "text": { "body": "Quero remarcar" }
        }]
      }
    }]
  }]
}

Três mudanças que merecem atenção:

  • Status chegam separados. sent, delivered, read e failed vêm em value.statuses[], referenciando o wamid que você guardou no envio.
  • Mídia vem por referência. Uma imagem recebida traz image.id; para baixar o arquivo, use os endpoints de mídia.
  • Eventos podem chegar repetidos. A Meta faz novas tentativas por até sete dias quando seu endpoint não responde 200, e isso pode duplicar notificações. Deduplique pelo id da mensagem.

Na Vectalk, o webhook é registrado por API, e você pode ter várias URLs por instância. Os detalhes estão na página de webhooks da documentação. Para exemplos completos de servidor, idempotência e fila, veja Webhooks da API do WhatsApp: guia prático.

7. Rode em paralelo e corte

Se você optou por um número novo, mantenha os dois por um período. Direcione primeiro os fluxos de resposta (que não dependem de template), depois os de notificação. Acompanhe as taxas de entrega e de falha pelos webhooks de status. Quando os números estiverem estáveis, desligue a sessão antiga.

Checklist de migração

ItemFeito?
Inventário de fluxos: resposta, iniciado pela empresa, sem equivalente☐
Portfólio empresarial criado e verificação solicitada☐
Forma de pagamento cadastrada na conta de mensagens☐
Decisão sobre o número: coexistência, exclusão do app ou número novo☐
Nome de exibição aprovado☐
Templates criados por categoria e aprovados☐
Base de contatos com registro de opt-in☐
Envio reescrito para POST /messages com wamid persistido☐
Controle da janela de 24 horas antes de mensagens livres☐
Webhook com resposta 200 rápida, fila e deduplicação☐
Tratamento de status failed e códigos de erro☐
Download de mídia por media_id☐
Sessão não oficial encerrada antes do registro do número☐
Monitoramento de qualidade e limite de mensagens☐

Consentimento: o ponto que muitas migrações esquecem

Com a API não oficial, muita base de contatos foi formada sem registro de permissão. A Política de Mensagens Comerciais só permite contatar quem forneceu o número e deu opt-in para receber mensagens, e exige respeitar pedidos de saída. Antes de disparar o primeiro template de marketing, separe os contatos com consentimento registrado. Mandar para uma base fria é a forma mais rápida de derrubar a qualidade de um número recém-migrado.

Como a Vectalk entra na migração

A Vectalk é um proxy gerenciado da Cloud API. Você conecta o número pelo Cadastro Incorporado da Meta, recebe um token da Vectalk e usa os mesmos payloads da documentação da Meta, trocando apenas a URL base e o token. Com um token de organização, uma única credencial acessa todas as contas conectadas; basta enviar o phone_number_id no corpo da requisição. Isso ajuda quem migra vários números de clientes ao mesmo tempo.

Para começar, crie a conta em apps.vectalk.com.br/register e siga o guia rápido. Dúvidas de conta ficam na Central de Ajuda.

Perguntas frequentes

Consigo migrar sem perder o número?

Sim, em dois cenários. Se o número está no app WhatsApp Business, a coexistência conecta o número à API sem tirá-lo do app. Se está no WhatsApp comum, você exclui a conta do app e registra o número na Cloud API; o número continua seu, mas o histórico do aparelho não é levado para a API.

O histórico de conversas vem junto?

Na migração tradicional, não. Na coexistência, a Meta permite sincronizar até seis meses de conversas individuais, se a empresa autorizar o compartilhamento, e a sincronização precisa ser feita em até 24 horas após a integração.

A Evolution API já não é oficial?

A Evolution API oferece mais de um tipo de integração. O modo baseado em Baileys usa o WhatsApp Web e não é oficial. Quando configurada com a Cloud API da Meta, ela passa a usar a API oficial. O que determina o risco é o canal, não o nome do projeto.

Vou pagar por mensagens que hoje são de graça?

Sim. Na API oficial, a Meta cobra por mensagem entregue, conforme categoria e país. Há franquias e janelas sem cobrança. Os valores para o Brasil estão em Quanto custa a API do WhatsApp no Brasil em 2026.

Posso continuar usando grupos?

Com limites. A API de Grupos da Meta exige conta comercial oficial e aceita até 8 participantes por grupo. Grupos grandes e comunidades continuam fora do escopo da API.

Fontes oficiais consultadas em 20/10/2026: Termos de Serviço do WhatsApp, Números de telefone comerciais, Webhooks da Cloud API, API de Grupos, Política de Mensagens Comerciais.

Integre o WhatsApp oficial ao seu sistema

A Vectalk entrega a Cloud API da Meta com os mesmos payloads e webhooks, um token para todas as contas e documentação completa.

Criar conta grátis
Ler a documentação