Migrar da Evolution API para a ZapZap: guia passo a passo

A Evolution API é de código aberto: o repositório oficial indica licença Apache 2.0 com condições adicionais de preservação de logo e aviso de uso, Node.js 20 ou superior, PostgreSQL ou MySQL e Redis recomendado. A própria descrição do projeto diz que a conexão por Baileys depende do WhatsApp Web e pode ter limitações em relação às APIs oficiais. Você escolhe o servidor, a versão e o momento de atualizar.

Na ZapZap, o servidor, a atualização e o monitoramento ficam com a gente, e a cobrança é por número ativo. Em troca, você não controla a infraestrutura nem o código. Os dois são não oficiais, então o risco de bloqueio do número é do mesmo tipo.

Software livre não é custo zero. Monte a conta com os seus números: servidor (VPS ou nuvem) que roda Node, banco e Redis; backup; monitoramento; e as horas de quem atualiza e investiga quando uma sessão cai. Some o custo mensal do servidor ao valor da hora do responsável vezes as horas por mês e divida pelo número de instâncias.

Compare com R$15 por número ativo ao mês. Se você opera muitas instâncias e já tem DevOps, a conta pode favorecer a Evolution. Se tem poucas instâncias e ninguém dedicado, costuma favorecer o gerenciado. O post sobre Evolution e WAHA hospedados x API gerenciada tem a fórmula completa.

A coluna da Evolution vem da documentação oficial (docs.evolutionfoundation.com.br, 27/10/2026). Versões diferentes da Evolution usam formatos diferentes, então confira a sua.

O envio muda em URL, cabeçalhos e forma do corpo: na Evolution, o texto fica dentro de um objeto textMessage; na ZapZap, é o campo text no topo. Mantenha uma função única de envio e troque só o interior dela.

No webhook, a Evolution envia o nome do evento em maiúsculas (por exemplo, MESSAGES_UPSERT); a ZapZap envia event em minúsculas (messages) dentro de um envelope com data.message. Escreva um adaptador e ligue na ZapZap só o evento messages, mais messages_update se você usa status de entrega.

// ANTES: Evolution API
// POST {EVOLUTION_URL}/message/sendText/{instancia}  header: apikey
// body: { number: "5511999999999", textMessage: { text: "Olá!" } }

// DEPOIS: ZapZap
export async function enviarWhatsApp(numero, texto) {
  const r = await fetch(
    "https://api.zapzapapi.com/api/v1/" + process.env.ZAPZAP_INSTANCE_ID + "/send/text",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.ZAPZAP_API_KEY,
        "x-api-secret": process.env.ZAPZAP_API_SECRET,
      },
      body: JSON.stringify({ number: numero, text: texto }),
      signal: AbortSignal.timeout(15000),
    }
  );
  if (!r.ok) throw new Error("ZapZap " + r.status + " " + (await r.text()));
  return r.json();
}

export function deZapZap(evento) {
  const m = evento?.data?.message;
  if (evento?.event !== "messages" || !m || m.fromMe) return null;
  return { telefone: String(m.chatid || "").replace(/\D/g, ""), texto: m.text || "" };
}

Crie a instância na ZapZap (Criar Instância) e conecte o número por QR code. As mensagens e contatos guardados no seu banco da Evolution continuam seus: exporte-os antes de desligar o servidor. Não mantenha o mesmo número conectado nos dois ao mesmo tempo.

Checklist: 1) criar a conta e testar com um número seu; 2) trocar a função de envio; 3) apontar o webhook para o adaptador e validar a assinatura (guia); 4) exportar o que quiser guardar da Evolution; 5) virar em horário calmo; 6) desligar o servidor antigo só depois de alguns dias de operação estável.

Continue na Evolution se você tem DevOps e quer o código e os dados dentro do seu ambiente, se opera muitas instâncias e a conta de servidor fecha a seu favor, ou se depende de uma integração específica dela. Veja também o comparativo Evolution API x ZapZap. Se você precisa de canal homologado pela Meta, a opção é a API oficial.