Instância do WhatsApp desconectou: causas e como reconectar

Você acorda, olha o log e vê dezenas de 502 seguidos. Nada mudou no seu código, o cliente não mexeu em nada, e mesmo assim as mensagens pararam de sair. Na esmagadora maioria das vezes a causa é uma só: a instância desconectou.

Instância de WhatsApp é uma sessão vinculada, do mesmo tipo que o WhatsApp Web cria quando você lê um QR Code. Sessão vinculada cai. Não é defeito da API — é característica do canal. O que separa uma operação estável de uma instável não é evitar toda queda, é detectar rápido e reconectar antes que a fila estoure.

Este guia cobre as causas reais, como monitorar e o procedimento de reconexão no Zapixo.

Por que uma instância cai

O celular ficou muito tempo offline

Esta é a causa número um, e a menos óbvia. A sessão vinculada depende do aparelho que leu o QR Code continuar existindo na rede de vez em quando. Se o celular fica dias sem conexão — desligado, sem chip, esquecido em uma gaveta —, o WhatsApp encerra os aparelhos vinculados. O prazo observado gira em torno de duas semanas.

Consequência prática: o celular do número não pode ser um aparelho descartável guardado. Ele precisa estar ligado, carregado e com internet.

Alguém desvinculou manualmente

Em Aparelhos conectados, dentro do WhatsApp, qualquer pessoa com o celular na mão vê a sessão da API listada e pode encerrá-la com dois toques. Acontece muito quando o aparelho é compartilhado ou quando alguém "limpa" as sessões achando que é invasão.

Estourou o limite de aparelhos vinculados

O WhatsApp permite um número limitado de dispositivos vinculados por conta. Se alguém vincula o WhatsApp Web no computador, o WhatsApp Desktop e mais um tablet, a sessão mais antiga — que costuma ser a da API — é derrubada para dar lugar.

O aplicativo foi atualizado ou reinstalado

Reinstalar o WhatsApp, restaurar backup ou trocar de aparelho encerra todas as sessões vinculadas. Migração de celular é um evento de desconexão garantido.

Otimização de bateria matou o app

Em Android, sistemas de economia de energia agressivos fecham o WhatsApp em segundo plano. O aparelho está ligado e com internet, mas o app não roda — e para a sessão vinculada isso equivale a estar offline.

O número foi banido

Caso mais grave e menos frequente. Aqui a instância não apenas desconecta: ela não reconecta. Se o QR Code é lido e a sessão cai de novo em segundos, ou se o WhatsApp no celular acusa restrição de conta, o problema não é técnico. As práticas que reduzem esse risco estão no guia sobre como evitar banimento.

Como detectar a queda

Existem três formas, da pior para a melhor.

Descobrir pelo erro de envio (ruim)

Se você só descobre a queda quando um 502 aparece, já perdeu mensagem. Serve como último recurso, não como monitoramento.

Consultar o status (bom)

O endpoint de status responde a situação atual da instância:

curl https://zapixo.com.br/api/v1/instances/minha-loja/status \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta:

{
  "instance": "minha-loja",
  "status": "connected",
  "raw": "open"
}

O campo status assume três valores:

Status	Significado	O que fazer
connected	Sessão ativa, pode enviar	Nada
connecting	Em processo de conexão	Aguardar, não enfileirar envio ainda
disconnected	Sessão caída	Parar os envios e reconectar

Uma verificação a cada poucos minutos, antes de processar a fila, já evita a maior parte do prejuízo. O campo raw traz o estado bruto, útil para diagnóstico quando o comportamento foge do esperado.

Receber o aviso por webhook (melhor)

Consultar status é polling — você pergunta e espera. O webhook inverte: a mudança de conexão chega ao seu servidor no momento em que acontece, como um evento connection.update. Configure a URL de status no painel da instância e trate o evento:

export async function POST(request) {
  const payload = await request.json();

  if (String(payload.event ?? "").toLowerCase().includes("connection")) {
    const estado = payload.data?.state ?? payload.data?.status;

    if (estado !== "open" && estado !== "connected") {
      await pausarFilaDeEnvio();
      await avisarEquipe(`Instância caiu: ${estado}`);
    } else {
      await retomarFilaDeEnvio();
    }
  }

  return Response.json({ received: true });
}

Além do seu webhook, o Zapixo dispara um e-mail de alerta para a conta quando uma instância que estava conectada cai. É a rede de segurança para o caso de o seu próprio monitoramento estar fora do ar.

O encaminhamento de webhook tenta três vezes, com intervalos crescentes de 1, 5 e 25 segundos, e registra a falha quando as três tentativas se esgotam. Ou seja: uma instabilidade curta no seu servidor não faz você perder o aviso de queda. Se quiser testar como o seu endpoint recebe esse payload antes de subir, use o testador de webhook.

Como reconectar

O procedimento é o mesmo do primeiro pareamento:

1. Entre no painel e abra a instância que caiu.
2. Peça para gerar o QR Code.
3. No celular do número, abra o WhatsApp → Aparelhos conectados → Conectar um aparelho.
4. Leia o código na tela.
5. Confirme que o status virou connected, pelo painel ou pelo endpoint de status.

O QR Code tem validade curta — em torno de um minuto. Se expirar, gere outro; não adianta insistir no antigo.

Importante: reconectar não reenvia sozinho o que falhou enquanto a instância estava fora. Isso é responsabilidade da sua fila, e é o principal motivo para não disparar direto do seu código sem intermediário.

O que fazer com as mensagens que falharam

Se você envia direto, sem fila, cada 502 durante a queda é uma mensagem perdida em definitivo. A estrutura mínima que evita isso:

1. Persista antes de enviar. Grave a mensagem com status pendente no seu banco.
2. Envie a partir da fila, atualizando para enviado com o messageId retornado, ou falhou com o erro.
3. Pause o consumo da fila quando o status for disconnected. Não adianta tentar: vai falhar e você só queima registro.
4. Retome quando voltar a connected, processando os pendentes na ordem.

O desenho completo de fila, retentativa e ordenação está no guia sobre rate limit e fila de mensagens.

Como reduzir a frequência das quedas

Use um celular dedicado, ligado na tomada. Nada de aparelho pessoal que viaja, fica sem bateria e troca de rede o dia inteiro.

Desative a otimização de bateria para o WhatsApp nas configurações do Android.

Não vincule outros dispositivos ao mesmo número. Cada WhatsApp Web aberto por um funcionário é uma vaga a menos e um risco de derrubar a sessão da API.

Avise a equipe que aquela sessão listada é a integração. Um aviso colado no aparelho evita a desvinculação por engano.

Deixe o Wi-Fi estável. Rede de convidado com portal de autenticação que expira a cada 24 horas derruba o aparelho silenciosamente.

Distribua o risco em mais de uma instância se a operação for crítica. Com duas ou três instâncias, a queda de uma não para tudo — os planos Pro e Agência existem para esse cenário.

Resumo

Queda de instância não é falha da integração, é característica de sessão vinculada de WhatsApp. A operação madura assume que vai cair e se organiza em torno disso: detecta pelo webhook em tempo real, confirma pelo endpoint de status, pausa a fila, reconecta pelo QR Code e retoma os pendentes na ordem.

Quem monta essa estrutura trata a queda como um incidente de dez minutos. Quem não monta descobre pelo cliente reclamando três dias depois.