Migrate from Z-API to ZapZap: endpoint mapping and step by step

Stays the same: you connect a WhatsApp number by QR code and use an HTTP API with JSON to send and a webhook to receive. Both are unofficial solutions with no Meta badge, and on both the number can be limited or banned if use is abusive.

Changes: authentication (Z-API uses the Client-Token header; ZapZap uses x-api-key and x-api-secret), field names (phone and message on Z-API; number and text on ZapZap), the webhook format and the pricing model. According to the Z-API site on 10/27/2026, the Ultimate plan costs R$99.99 per instance per month and Partner, for 10 or more instances, R$89.99. ZapZap charges R$15 per active number per month, with no per-message fee. The plans have different features, so compare what you actually use before deciding.

The table covers what almost every project uses. For the rest, the ZapZap reference lists every endpoint. The Z-API column comes from its documentation (developer.z-api.io, 10/27/2026); where the page did not carry the data, the cell says to check.

On each row, read the Send Text, Send Media and Check Number references before switching.

The send change is mechanical. Swap the URL, remove the Client-Token, add the two ZapZap headers and rename the fields. The number keeps country code and digits only.

Create a thin function in your code (sendWhatsApp(number, text)) and change only what is inside it. That keeps the migration in one place, and going back too.

// ANTES: Z-API (confira a URL e o corpo na documentação da Z-API)
// headers: { "Client-Token": process.env.ZAPI_CLIENT_TOKEN }
// body:    { phone: "5511999999999", message: "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(); // { messageId, status }
}

On Z-API, an incoming message arrives with top-level fields such as phone, fromMe, messageId, instanceId and text.message (callback documentation, 10/27/2026). On ZapZap, the event comes in an envelope: event, data.message.text, data.message.chatid and data.message.fromMe, plus delivery_id and instance_id.

Write an adapter that converts the ZapZap event into the internal format your system already understands. Then the rest of the code does not change. Set the URL in configure webhook, turn on only the messages event and validate the signature as described in the webhooks in production guide.

// Converte o evento da ZapZap para o formato que o seu sistema já usa
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 || "",
    idMensagem: evento.event_id || evento.delivery_id,
  };
}

The number is yours: in ZapZap you create an instance (Create Instance) and connect the same number by QR code. Conversation history from the other service is not migrated through an API; save what you need before. The same number should not be active on both services at once, so plan a short switching window, preferably off-peak.

Checklist: 1) create the account and the instance; 2) test send and receive with a number of your own; 3) swap the send function; 4) point the webhook and validate the signature; 5) cut over at a calm hour; 6) disconnect the old instance only after confirming the new flow; 7) watch the first hours in the logs and in webhook deliveries.

Z-API has extensive documentation, local support and, according to its site, an Ultimate plan with no message limit and no per-message cost. If your use depends on a specific feature of theirs that ZapZap lacks, or if the operation is stable and the cost makes sense, migrating may not be worth the effort. If you need a channel sanctioned by Meta, neither fits: the option is the official API. The Z-API vs ZapZap comparison details price and limits with source and date.