WhatsApp desconecta sozinho na API: causas e solução

Comece pelo status da instância. A resposta traz o estado atual (disconnected, connecting ou connected) e, em instâncias desconectadas, campos como lastDisconnect e lastDisconnectReason, que registram quando e por qual motivo a conexão terminou (por exemplo, desconexão pedida pela própria API). Não é uma lista fechada de motivos: trate o texto como pista e cruze com a tabela abaixo.

Depois olhe o seu lado. Alguém da equipe chamou desconectar instância ou reiniciar instância? Um script de manutenção, um teste automatizado ou uma automação mal desenhada que chama desconectar em loop explicam muitos casos de queda recorrente.

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

Sobre saldo: a ZapZap suspende instâncias quando o saldo não cobre a renovação depois do período de carência, e a reativação após o pagamento deixa a instância desconectada, exigindo novo pareamento. É por isso que manter o saldo com folga evita a queda. Os detalhes de cobrança estão em preços.

Sobre o celular: a conexão de aparelhos adicionais depende do aparelho principal. Se o WhatsApp do celular principal ficar muito tempo sem uso, o WhatsApp pode encerrar as sessões conectadas. Consulte o artigo 'Sobre dispositivos conectados' na Central de Ajuda do WhatsApp para as regras atuais, porque elas mudam.

Se a instância ficou desconectada, o caminho é parear de novo: peça o QR em QR Code da instância ou use o pareamento por código em conectar instância. O passo a passo e os códigos de erro estão no guia de QR code que não aparece.

Se a instância aparece conectada mas não responde, o reinício do runtime pode resolver. Ele não apaga a sua configuração. Se a instância estiver desconectada, o reinício não substitui o pareamento: será preciso ler o QR de novo. Registre cada reconexão com data e motivo; três quedas na mesma semana pedem investigação de causa, não só reconexão.

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"

Ligue o evento connection no webhook. Ele dispara a cada mudança de estado do número (conectado, desconectado, conectando). Ao receber desconectado, o seu sistema pode abrir um alerta para a equipe, pausar filas de envio e, se a regra de negócio permitir, avisar o cliente final de que o atendimento está instável. A configuração está em configurar webhook, e o tratamento seguro do evento no guia de webhook em produção.

Como segunda rede, faça uma checagem periódica do status da instância. Webhook pode falhar, e um monitor simples que consulta o status a cada poucos minutos e alerta em caso de queda cobre esse buraco. Se você usa o n8n, a integração com n8n traz o gatilho de webhook pronto para essa automação.

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);

Quedas recorrentes têm menos a ver com sorte e mais com processo. Tenha um responsável pelo celular do número, mantenha o aplicativo atualizado, não remova o aparelho conectado sem avisar a operação e evite usar o mesmo número em outra ferramenta ao mesmo tempo. Para operações em que o número é crítico, mantenha um número reserva e separe funções (atendimento, cobrança, vendas) em instâncias diferentes, de modo que uma queda não pare tudo.

Se a desconexão veio acompanhada de restrição pelo WhatsApp, ela não é uma falha técnica a ser consertada com reinício. Nenhuma ferramenta elimina esse risco, e o uso de API não oficial não está previsto nos Termos do WhatsApp. O guia anti-bloqueio no WhatsApp explica o que reduz o risco e o que não o elimina.

[ ] Há um responsável pelo celular do número e pelo aplicativo atualizado

[ ] Ninguém remove o aparelho conectado sem avisar a operação

[ ] O saldo cobre a renovação com folga

[ ] Scripts e automações não chamam desconectar ou reiniciar sem necessidade

[ ] O evento connection está ligado no webhook e alerta a equipe

[ ] Existe um monitor de status como segunda rede

[ ] Há um número reserva e um canal alternativo para avisar clientes

Cada queda que se repete é um dado. Anote a data, o horário, o lastDisconnectReason e o que mudou naquele dia (deploy, troca de celular, campanha). Em poucas semanas o padrão aparece, e é quase sempre uma causa operacional que se resolve com processo e não com tecnologia.