Migrar da Evolution API para a API oficial do WhatsApp

Em resumo: para levar um bot ou uma automação da Evolution API no modo Baileys para a API Cloud oficial da Meta, conecte o número ao ZapClaw pela Coexistência, envie pela API REST do ZapClaw em vez de /message/sendText e leia o webhook do ZapClaw em vez de messages.upsert. O número continua funcionando no app WhatsApp Business no seu celular. Abaixo: os passos, os campos de envio de texto, de mídia e de template e os principais campos de webhook lado a lado, e o que não tem equivalente na API oficial.

O ZapClaw é um gateway hospedado na API Cloud da Meta: nenhum servidor da Evolution para manter no ar e nenhum app próprio na Meta.

Plano Business: R$ 99 por mês, com números ilimitados

Comece grátis Ver o mapeamento dos campos

Por que migrar para a API oficial

As políticas da Meta continuam valendo na API oficial: a Meta pode restringir ou desativar uma conta que as descumpre, e a API do ZapClaw passa a responder 403 com o motivo (erros, em inglês).

O que você precisa para conectar

Não precisa de CNPJ nem de empresa verificada para conectar. A lista completa.

A migração, passo a passo

  1. Mapeie o código primeiro. Troque as chamadas de envio e o tratamento do webhook com as tabelas abaixo, ou coloque o shim na frente do seu fluxo para ele manter as chamadas da Evolution enquanto você reescreve.
  2. Faça backup das conversas no app WhatsApp Business e confira os requisitos acima.
  3. Conecte o número. Crie a sua conta no ZapClaw e conecte o número na janela da Meta, pelo painel. A Meta então desconecta todos os dispositivos vinculados à conta, e a instância da Evolution perde a sessão. Apague a instância depois, para ninguém vinculá-la de novo lendo o QR code dela e dois sistemas responderem ao mesmo cliente.
  4. Configure o webhook. No painel, em Webhook, cole a sua URL HTTPS pública, escolha os eventos e copie a chave de assinatura. Marque Mensagens enviadas pelo app WhatsApp Business se o seu fluxo lia mensagens com fromMe: true.
  5. Crie uma chave de API e envie com ela no cabeçalho X-API-Key para https://api.zapclaw.app. O campo from indica o número, então uma chave envia por todos os números da conta.
  6. Crie os seus templates. Fora da janela de 24 horas, e para escrever primeiro, a Meta só aceita um template aprovado. Crie pelo painel ou com POST /api/v1/send/templates, e passe language ao enviar um: o padrão da API é pt_BR.
  7. Teste. Clique em Enviar evento de teste na página Webhook do painel, depois escreva para o seu número de outro celular e confira se o seu fluxo recebe a mensagem e responde.

Envio: as chamadas da Evolution API e o equivalente no ZapClaw

Evolution API v2 na versão 2.3.7, a última versão estável quando conferimos. Os caminhos da Evolution são relativos ao seu servidor da Evolution, e os do ZapClaw a https://api.zapclaw.app.

Evolution API v2 ZapClaw
Enviar texto POST /message/sendText/{instance} POST /api/v1/send/text
Enviar mídia POST /message/sendMedia/{instance}, além de /sendWhatsAppAudio e /sendSticker POST /api/v1/send/media
Enviar um template POST /message/sendTemplate/{instance} POST /api/v1/send/template
Autenticação Cabeçalho apikey Cabeçalho X-API-Key
O seu número A instância, no caminho from, no corpo
Destinatário number: dígitos com o código do país to: só dígitos, sem @s.whatsapp.net
Texto text no validador da 2.3.7, textMessage.text no esquema da documentação text, até 4.096 caracteres
Prévia de link linkPreview previewUrl
Responder a uma mensagem quoted.key.id replyTo: o wamid da mensagem
Tipo de mídia mediatype type: image, video, audio, document ou sticker
Arquivo de mídia media: uma URL ou base64 link, uma URL https pública, ou mediaId de POST /api/v1/media
Legenda e nome do arquivo caption, fileName caption (imagem, vídeo, documento), filename (documento)
Áudio de voz e figurinha audio em /sendWhatsAppAudio, sticker em /sendSticker type audio ou sticker (WebP), com link ou mediaId
Campos do template name, language, components templateName, language, components
Atraso e menções delay, mentioned, mentionsEveryOne Sem equivalente. POST /api/v1/send/typing mostra o indicador de digitação numa mensagem que você recebeu.
Resposta key.id, key.remoteJid, status 201 com message.wamid, message.to e message.status

Localização, cartões de contato e reações vão por POST /api/v1/send/location, /send/contacts e /send/reaction (referência da API, em inglês). O shim mais abaixo ainda não converte essas chamadas: envie direto ao ZapClaw.

Recebimento: o messages.upsert e o equivalente no ZapClaw

A Evolution envia event, instance, data, sender e mais alguns campos; os caminhos de data abaixo são os de um evento messages.upsert. O ZapClaw envia event, timestamp, data e account para uma URL só, para todos os seus números.

Evolution API v2 ZapClaw
Evento messages.upsert message.received, também no cabeçalho X-ZapClaw-Event
Qual dos seus números instance, sender account.phone_number_id, account.display_phone_number
Remetente data.key.remoteJid: o número mais @s.whatsapp.net data.from, só dígitos, e data.user_id, o id permanente do contato
Enviada por você data.key.fromMe: true Um evento separado, message.echo, com data.to, para mensagens enviadas pelo app WhatsApp Business ou pelo WhatsApp Web (opcional)
Id da mensagem data.key.id data.message_id, um wamid
Nome do contato data.pushName data.contact_name
Horário data.messageTimestamp: segundos, como número data.timestamp: segundos, como string
Tipo data.messageType: conversation, imageMessage, audioMessage e assim por diante data.type: text, image, audio, video, document, sticker e outros
Texto data.message.conversation data.text.body
Arquivo de mídia data.message.mediaUrl com armazenamento S3 ou MinIO ativo, ou data.message.base64 data.<type>.media_url, baixada com a sua X-API-Key
Legenda e tipo MIME data.message.imageMessage.caption, data.message.imageMessage.mimetype data.image.caption, data.image.mime_type
Nome do arquivo data.message.documentMessage.fileName data.document.filename
Áudio de voz data.message.audioMessage.ptt data.audio.voice
Mensagem citada data.contextInfo.stanzaId data.context.id
Status de entrega messages.update, com SERVER_ACK, DELIVERY_ACK, READ ou ERROR message.status, com data.status igual a sent, delivered, read ou failed
Autenticação da requisição Nenhuma por padrão. Cabeçalhos opcionais escolhidos por você, e um cabeçalho jwt_key vira um token Authorization: Bearer assinado X-ZapClaw-Signature: um HMAC-SHA256 do corpo bruto, feito com a sua chave de assinatura (como verificar, em inglês)

Um link de mídia do ZapClaw precisa da sua chave de API, e a Meta guarda a mídia recebida por cerca de 30 dias, então baixe o que quiser manter. As entregas podem chegar fora de ordem: quando a ordem importa, ordene pelo sequence do nível superior.

O que não tem equivalente, e o que fazer no lugar

Continue usando o app WhatsApp Business no celular: a Meta desconecta um número em Coexistência cujo app fica cerca de 14 dias sem uso, e o ZapClaw avisa o seu webhook com um evento account.account_update (detalhes, em inglês).

Um adaptador curto

Duas funções para Node.js 18 ou mais novo, sem dependências: a primeira envia onde o seu código chamava sendText, a segunda transforma um message.received do ZapClaw nos campos do messages.upsert que o seu fluxo já lê. Confira o cabeçalho X-ZapClaw-Signature antes de confiar num corpo.

// Sending: what was POST /message/sendText/{instance} with an apikey header
const sendText = async ({ number, text }) => {
  const res = await fetch('https://api.zapclaw.app/api/v1/send/text', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ZAPCLAW_API_KEY,
    },
    body: JSON.stringify({ from: process.env.ZAPCLAW_FROM, to: number, text }),
  });
  if (!res.ok) throw new Error(`ZapClaw answered ${res.status}`);
  const { message } = await res.json();
  return { key: { id: message.wamid } }; // where your code read key.id
};

// Receiving: the messages.upsert fields, taken from a message.received body
const fromZapClaw = (body) => ({
  remoteJid: `${body.data.from}@s.whatsapp.net`,
  id: body.data.message_id,
  pushName: body.data.contact_name,
  messageTimestamp: Number(body.data.timestamp),
  conversation: body.data.text ? body.data.text.body : undefined,
});

A versão completa está no GitHub: zapclaw/migrate-to-whatsapp-official-api converte texto, mídia, templates, status de entrega e webhooks, e traz um pequeno shim. Uma chamada que não é convertida, como uma localização, um cartão de contato ou uma reação, é recusada com um código de erro claro: envie essas chamadas direto pela API do ZapClaw. Aponte para o shim a URL base da Evolution que o seu fluxo usa: ele repassa ao ZapClaw as chamadas que converte e transforma os webhooks assinados do ZapClaw de volta em messages.upsert, para você migrar primeiro e reescrever depois. Licença MIT.

Se você usava outros recursos da Evolution

Quanto custa

A Meta cobra as tarifas de mensagem do WhatsApp direto de você, sem margem do ZapClaw. Todos os planos e preços.

Veja também

Fontes

Conferido em 15 de outubro de 2026. A Evolution API muda entre versões, então confira a documentação da versão que você usa.

Leve os seus fluxos da Evolution para a API oficial

Comece no plano grátis: um número, sem cartão. Passe para o plano Business quando precisar de mais números ou de mais mensagens.

Comece grátis Ler a documentação do webhook