WhatsApp disconnects on its own in the API: causes and fixes

Start with the instance status. The response carries the current state (disconnected, connecting or connected) and, on disconnected instances, fields like lastDisconnect and lastDisconnectReason, which record when and why the connection ended (for example, a disconnect requested by the API itself). It is not a closed list of reasons: treat the text as a clue and cross-check it with the table below.

Then look at your own side. Did someone on the team call disconnect instance or reset instance? A maintenance script, an automated test or a badly designed automation that calls disconnect in a loop explains many cases of recurring drops.

curl "https://api.zapzapapi.com/api/v1/$INSTANCE_ID/instance/status" \
  -H "x-api-key: $ZAPZAP_API_KEY" \
  -H "x-api-secret: $ZAPZAP_API_SECRET"
# veja instance.status e, quando houver, instance.lastDisconnect e instance.lastDisconnectReason

On balance: ZapZap suspends instances when the balance does not cover the renewal after the grace period, and reactivation after payment leaves the instance disconnected, requiring a new pairing. That is why keeping a comfortable balance prevents the drop. Billing details are on the pricing page.

On the phone: linked devices depend on the primary device. If the primary phone's WhatsApp goes unused for a long time, WhatsApp may end the linked sessions. See the 'About linked devices' article in the WhatsApp Help Center for the current rules, because they change.

If the instance is disconnected, the path is to pair again: request the QR at instance QR code or use pairing by code in connect instance. The step by step and the error codes are in the guide on the QR code not showing.

If the instance shows as connected but does not respond, restarting the runtime may fix it. It does not erase your configuration. If the instance is disconnected, a restart is not a substitute for pairing: you will need to scan the QR again. Log every reconnection with a date and reason; three drops in the same week call for root-cause work, not just reconnecting.

BASE="https://api.zapzapapi.com/api/v1"
H1="x-api-key: $ZAPZAP_API_KEY"
H2="x-api-secret: $ZAPZAP_API_SECRET"

curl -X POST "$BASE/$INSTANCE_ID/instance/reset" -H "$H1" -H "$H2"
sleep 10
curl "$BASE/$INSTANCE_ID/instance/status" -H "$H1" -H "$H2"

Turn on the connection event in the webhook. It fires on every change of the number's state (connected, disconnected, connecting). When you receive disconnected, your system can open an alert for the team, pause send queues and, if the business rule allows, tell the end customer that service is unstable. The setup is in set webhook, and safe handling of the event is in the guide on webhooks in production.

As a second safety net, poll the instance status periodically. Webhooks can fail, and a simple monitor that checks the status every few minutes and alerts on a drop covers that gap. If you use n8n, the n8n integration has the webhook trigger ready for that automation.

const BASE = "https://api.zapzapapi.com/api/v1";
const headers = {
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};

async function checar(id) {
  const resp = await fetch(BASE + "/" + id + "/instance/status", { headers });
  if (!resp.ok) return console.error("status falhou", resp.status);
  const { instance } = await resp.json();
  if (instance.status !== "connected") {
    console.error("ALERTA: instância", id, "está", instance.status, instance.lastDisconnectReason || "");
    // aqui: enviar e-mail, Slack, etc.
  }
}

setInterval(() => checar(process.env.INSTANCE_ID).catch(console.error), 3 * 60 * 1000);

Recurring drops have less to do with luck and more to do with process. Have an owner for the number's phone, keep the app updated, do not remove the linked device without telling operations and avoid using the same number in another tool at the same time. For operations where the number is critical, keep a spare number and split functions (support, billing, sales) across different instances, so one drop does not stop everything.

If the disconnect came with a restriction from WhatsApp, it is not a technical failure to be fixed with a restart. No tool eliminates that risk, and using an unofficial API is not covered by the WhatsApp Terms. The guide on WhatsApp anti-ban explains what lowers the risk and what does not remove it.

[ ] There is an owner for the number's phone and for keeping the app updated

[ ] Nobody removes the linked device without telling operations

[ ] The balance covers the renewal with room to spare

[ ] Scripts and automations do not call disconnect or reset unnecessarily

[ ] The connection event is on in the webhook and alerts the team

[ ] There is a status monitor as a second safety net

[ ] There is a spare number and an alternate channel to notify customers

Every drop that repeats is a data point. Write down the date, the time, the lastDisconnectReason and what changed that day (a deploy, a phone swap, a campaign). Within a few weeks the pattern shows up, and it is almost always an operational cause that gets fixed with process, not technology.