Migrar do WAHA para a API oficial do WhatsApp

Em resumo: para levar um bot ou uma automação do WAHA 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 /api/sendText e leia o webhook do ZapClaw em vez do evento message do WAHA. O número continua funcionando no app WhatsApp Business no seu celular. Abaixo: os passos, os campos de envio de texto e de mídia 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 ou sessão do WAHA 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 do WAHA enquanto você reescreve.
  2. Confira o número. A Coexistência conecta números que rodam no app WhatsApp Business, não no WhatsApp comum. Faça backup das conversas no app 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, inclusive a sessão do WAHA. Pare ou apague a sessão no WAHA depois, para ninguém escanear o QR code dela de novo 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 escutava message.any para as suas próprias mensagens.
  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 do WAHA e o equivalente no ZapClaw

Os caminhos do WAHA são relativos ao seu servidor do WAHA, e os do ZapClaw a https://api.zapclaw.app.

WAHA ZapClaw
Enviar texto POST /api/sendText POST /api/v1/send/text
Enviar mídia /api/sendImage, /api/sendVideo, /api/sendVoice, /api/sendSticker, /api/sendFile POST /api/v1/send/media com type image, video, audio, sticker ou document
Autenticação Cabeçalho X-Api-Key Cabeçalho X-API-Key, com uma chave do ZapClaw
O seu número session, no corpo from, no corpo
Destinatário chatId: o número mais @c.us to: o número, só dígitos
Texto text text, até 4.096 caracteres
Prévia de link linkPreview previewUrl
Responder a uma mensagem reply_to replyTo: o wamid da mensagem
Arquivo de mídia file.url, ou file.data em base64, com file.mimetype link, uma URL https pública, ou mediaId de POST /api/v1/media
Nome do arquivo file.filename filename (documento)
Legenda caption caption (imagem, vídeo, documento)
Conversão de formato convert, asNote Sem equivalente: envie um formato que o WhatsApp aceita
Menções mentions Sem equivalente

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 evento message e o equivalente no ZapClaw

O WAHA envia um envelope com event, session, me e payload; os caminhos de payload abaixo são os de um evento message. O ZapClaw envia event, timestamp, data e account para uma URL só, para todos os seus números.

WAHA ZapClaw
Evento message; message.any inclui também as suas message.received; as suas mensagens enviadas pelo app chegam como message.echo (opcional)
Qual dos seus números session, me.id account.phone_number_id, account.display_phone_number
Remetente payload.from: o número mais @c.us data.from, só dígitos, e data.user_id, o id permanente do contato
Enviada por você payload.fromMe O evento message.echo, com data.to
Id da mensagem payload.id data.message_id, um wamid
Nome do contato Fora do payload documentado; fica no _data próprio do engine data.contact_name
Horário payload.timestamp: segundos nos exemplos da documentação data.timestamp: segundos, como string
Texto payload.body, que traz a legenda nas mídias data.text.body, ou data.<type>.caption nas mídias
Tem mídia payload.hasMedia data.type é image, audio, video, document ou sticker
Arquivo de mídia payload.media.url, baixada com a sua X-Api-Key data.<type>.media_url, baixada com a sua X-API-Key
Tipo MIME e nome do arquivo payload.media.mimetype, payload.media.filename data.<type>.mime_type, data.document.filename
Mensagem citada payload.replyTo.id data.context.id
Status de entrega message.ack, com payload.ackName igual a ERROR, PENDING, SERVER, DEVICE, READ ou PLAYED message.status, com data.status igual a failed, sent, delivered ou read
Autenticação da requisição Opcional: X-Webhook-Hmac, um HMAC SHA-512 do corpo, quando a sessão tem uma chave Sempre: 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 /api/sendText, a segunda transforma um message.received do ZapClaw nos campos de payload que o seu fluxo já lê. Confira o cabeçalho X-ZapClaw-Signature antes de confiar num corpo.

// Sending: what was POST /api/sendText with an X-Api-Key header
const sendText = async ({ chatId, 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: chatId.replace(/@c\.us$/, ''),
      text,
    }),
  });
  if (!res.ok) throw new Error(`ZapClaw answered ${res.status}`);
  return (await res.json()).message; // message.wamid is the new message id
};

// Receiving: the payload of a WAHA message event, taken from a message.received body
const MEDIA = ['image', 'audio', 'video', 'document', 'sticker'];
const fromZapClaw = (body) => {
  const d = body.data;
  const media = MEDIA.includes(d.type) ? d[d.type] : null;
  return {
    from: `${d.from}@c.us`,
    fromMe: false,
    id: d.message_id,
    timestamp: Number(d.timestamp),
    body: d.text ? d.text.body : (media ? media.caption || '' : ''),
    hasMedia: Boolean(media),
    media: media ? { url: media.media_url, mimetype: media.mime_type } : null,
  };
};

A versão completa está no GitHub: zapclaw/migrate-to-whatsapp-official-api converte texto, mídia, 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 do WAHA que o seu fluxo usa: ele repassa ao ZapClaw as chamadas que converte e transforma os webhooks assinados do ZapClaw de volta em eventos message, message.any e message.ack, para você migrar primeiro e reescrever depois. Licença MIT.

Se o seu cenário é diferente

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. Os campos do WAHA podem variar conforme o engine, então confira a documentação do engine que você usa.

Leve os seus fluxos do WAHA 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