Enviar WhatsApp com Node.js em 5 minutos

1) Uma conta na ZapZap e uma instância conectada por QR code. Contas novas recebem crédito de boas-vindas ao verificar o telefone, conforme a campanha vigente; o início rápido mostra onde clicar. 2) Sua API key, seu API secret e o ID da instância. 3) Node 18 ou mais novo (node -v).

Coloque as credenciais em variáveis de ambiente, nunca no código. A autenticação são dois cabeçalhos em toda requisição, x-api-key e x-api-secret.

export ZAPZAP_INSTANCE_ID="your-instance-id"
export ZAPZAP_API_KEY="your-api-key"
export ZAPZAP_API_SECRET="your-api-secret"

Crie o arquivo send.mjs com o código abaixo e rode com node send.mjs. A extensão .mjs habilita await no nível do arquivo; em CommonJS, envolva a chamada numa função async. Use o seu próprio número primeiro. O número vai com DDI e só dígitos, sem +, espaços ou traços.

const BASE = "https://api.zapzapapi.com/api/v1";
const { ZAPZAP_INSTANCE_ID, ZAPZAP_API_KEY, ZAPZAP_API_SECRET } = process.env;

async function zapzap(path, body) {
  const res = await fetch(BASE + "/" + ZAPZAP_INSTANCE_ID + path, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": ZAPZAP_API_KEY,
      "x-api-secret": ZAPZAP_API_SECRET,
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(20_000), // never leave a call hanging
  });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) throw new Error("ZapZap " + res.status + ": " + JSON.stringify(data));
  return data;
}

// number: country code + digits only (no +, spaces or dashes)
console.log(await zapzap("/send/text", { number: "5511999999999", text: "Hello from Node.js" }));

Arquivos passam por /send/media. O campo type escolhe o tipo (image, video, audio, ptt, document, sticker), file é uma URL pública, text é a legenda e docName é o nome do arquivo nos documentos. O arquivo precisa estar acessível por uma URL pública; se ele está no seu disco, suba para um armazenamento e use um link temporário.

await zapzap("/send/media", {
  number: "5511999999999",
  type: "document",
  file: "https://example.com/invoice-1042.pdf",
  text: "Your invoice",
  docName: "invoice-1042.pdf",
});

Registre a sua URL pública como webhook da instância com o evento de mensagens ligado (veja configurar webhook). No desenvolvimento local você precisa de um túnel, porque a API precisa alcançar você pela internet.

Descarte sempre os eventos fromMe, ou uma resposta automática responde a si mesma em loop. Confira o formato exato com uma mensagem real primeiro; para validar o cabeçalho X-ZapZap-Signature e eliminar entregas repetidas, siga webhooks em produção.

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook", (req, res) => {
  res.sendStatus(200); // answer first, process after

  const msg = req.body?.data?.message;
  if (!msg || msg.fromMe) return; // ignore your own messages

  console.log("from " + msg.chatid + ": " + msg.text);
  // reply, save to a database, call an AI agent...
});

app.listen(3000, () => console.log("listening on :3000"));

Tente de novo apenas em 429 e 5xx, com esperas crescentes. Um 400, 401 ou 403 significa que a requisição ou as credenciais estão erradas, e repetir só produz mais erros.

async function withRetry(fn, tries = 4) {
  for (let i = 0; ; i++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = /ZapZap (429|5\d\d)/.test(err.message);
      if (!retryable || i >= tries - 1) throw err;
      await new Promise((r) => setTimeout(r, 2 ** i * 1000));
    }
  }
}

await withRetry(() => zapzap("/send/text", { number: "5511999999999", text: "Retried send" }));

Credenciais só em variáveis de ambiente, nunca no git. Timeout em toda chamada e retry só em 429 e 5xx. Em listas, envie um por vez com uma pausa aleatória entre as mensagens em vez de disparar tudo em paralelo; trate os valores da pausa como um ponto de partida seu, não como regra do WhatsApp, e para campanhas grandes a fila do servidor tira isso do seu app. Envie só para quem concordou em receber e respeite quem pediu para sair.

Não oficial significa risco de bloqueio. Ritmo, aquecimento e listas limpas reduzem, nada elimina. Use um número que você possa perder enquanto testa e leia o guia anti-bloqueio. Se você precisa de canal homologado, veja API oficial x ZapZap. Para planejar: R$15 por número ativo por mês, pré-pago, sem cobrança por mensagem (preços).

Lista completa de endpoints na referência da API e no arquivo OpenAPI. Prefere outra linguagem? Os mesmos endpoints funcionam em Python e nos outros guias do blog, ou sem código no n8n. Para a versão com mais detalhes deste guia, veja enviar WhatsApp com Node.js. Os SDKs oficiais ainda não estão publicados no npm nem no PyPI; o código-fonte está no GitHub em zapzap-sdk-node, zapzap-sdk-python e zapzap-sdk-php, e a API REST funciona direto com o fetch, como acima.