Quando uma instância deixa de enviar ou receber mensagens, comece verificando o estado no painel ou pelo endpoint documentado. Uma sessão desconectada pode precisar de novo pareamento. Evite apagar a instância antes de entender se a ação remove dados ou configurações que sua integração usa.

Confira o estado antes de agir

No painel StackZap Cloud, abra o ambiente e examine o indicador da instância. Pela API, consulte GET /v1/instances/{id}/status usando URL, ID e API Key do mesmo ambiente. Registre o horário e o estado apresentado.

Diagnóstico sem recriar a instância
  1. 01Consulte o estado atual
  2. 02Confira celular e conexão
  3. 03Use reconectar se necessário
  4. 04Confirme o novo estado

Reconectar pelo painel ou API

Use a ação de reconexão disponível no painel ou o endpoint POST /v1/instances/{id}/reconnect documentado para a versão instalada. Se o fluxo gerar QR Code ou código de pareamento, conclua a confirmação no celular antes de fazer novas chamadas de envio.

Na instalação self-hosted, confira também se o serviço e o banco estão operacionais. No Cloud, use o widget de suporte no painel se a ação não avançar ou se houver uma mensagem de erro persistente.

Desconectar quando necessário

A StackZap documenta POST /v1/instances/{id}/logout para encerrar a sessão vinculada. Antes de usá-lo, confirme a instância e o impacto esperado na sua operação. Um logout requer novo pareamento antes que aquela sessão volte a operar.

Não compartilhe QR Code, código de pareamento ou API Key em chamados públicos. Se a conexão oscilar, anote o estado, o horário e o identificador da instância e envie esses dados sem segredos ao suporte. Consulte a referência de conexão para confirmar os passos atuais.

Diferencie uma queda temporária de sessão encerrada

Antes de reconectar, identifique o estado reportado e o impacto para sua operação. Uma falha de rede breve, um celular desligado, um pareamento pendente e uma sessão encerrada podem exigir ações diferentes. Consulte o status, observe se o celular mantém o dispositivo vinculado e confira a mensagem no painel. Não chame o endpoint repetidamente enquanto a primeira solicitação está em andamento.

Registre uma linha do tempo: horário da última operação bem-sucedida, quando a desconexão foi percebida, estado atual, mudanças recentes e tentativa feita. Isso permite reconhecer se o problema começou após logout manual, troca de telefone ou mudança da rede. No Cloud, o painel centraliza a instância; no self-hosted, verifique também a disponibilidade da aplicação e dos serviços.

Prepare os sistemas dependentes

Uma instância pode alimentar filas, webhooks, CRM, chatbot e automações. Antes de manutenção ou desconexão, decida o que fazer com operações pendentes. Pause produtores de novas mensagens, mas preserve a fila durável se ela puder ser retomada após reconectar. Avise operadores e evite que cada um inicie um pareamento ao mesmo tempo.

Uma reconexão normal deve manter a identidade usada pela aplicação, mas não assuma que toda reinicialização preserva todos os dados. Confirme o comportamento documentado para o comando e versão. Se uma mudança de conta ou ambiente for planejada, trate como migração: atualize credenciais, endpoints e consumidores com um plano de reversão.

Procedimento de reconexão

  1. Consulte o estado e confirme ambiente e ID.
  2. Pause envios automáticos se houver risco de duplicidade.
  3. Confira no WhatsApp se a sessão ainda está vinculada.
  4. Acione a reconexão suportada pelo painel ou API, conforme documentação.
  5. Se surgir QR ou código, use o valor atual e conclua pelo aplicativo.
  6. Consulte novamente até ter resultado conclusivo, com intervalos razoáveis.
  7. Faça um teste controlado e retome a fila gradualmente.

Se o estado não avançar, não crie outras instâncias para “destravar” sem orientação. Guarde horários e resposta da API, redigindo dados sensíveis. O suporte consegue investigar melhor com ambiente, ID e etapa, sem chave ou QR.

Como desconectar intencionalmente

O logout encerra a sessão vinculada e pode exigir novo pareamento para voltar a operar. Use-o quando houver razão clara, como remover uma conta da instância ou finalizar uma integração. Antes de confirmar, verifique se automações ainda podem acionar envios, se a equipe foi informada e como o serviço será retomado. Uma desconexão planejada reduz falhas confusas em tarefas pendentes.

Não use logout como tentativa genérica de recuperação. A ação altera o estado da conta e pode prolongar a indisponibilidade. Se o objetivo é renovar uma conexão oscilante, consulte primeiro o fluxo de reconexão e o diagnóstico da versão. Evite disponibilizar o botão para usuários sem responsabilidade sobre o canal.

Fila durante uma desconexão

Decida explicitamente se mensagens não processadas devem esperar, expirar ou ser canceladas. Notificações de prazo curto podem perder sentido depois de horas; confirme o estado do evento de negócio antes de enviar tardiamente. Não descarte silenciosamente mensagens sem registrar a decisão. Uma fila deve distinguir pendente, enviado, falha transitória, falha permanente e resultado incerto, conforme o que a aplicação consegue observar.

Depois de reconectar, retome gradualmente e respeite as cotas atuais. Use deduplicação para que uma tentativa sem resposta não resulte em duas mensagens. Não reapresente a fila inteira se alguns itens podem ter sido aceitos antes da queda.

Quando escalar para suporte

Peça ajuda se o painel ou endpoint mostrar erro persistente, se o pareamento for rejeitado repetidamente ou se o estado variar de forma inesperada. Informe ambiente, ID da instância, horários com fuso, estado observado, ação executada e status HTTP quando houver. Não envie credenciais, QR Codes, códigos, conversas ou exportações completas. No Cloud, use o widget do ambiente ou o WhatsApp de atendimento durante o horário divulgado.

Para self-hosted, reúna versão da StackZap, logs sanitizados, saúde do host, conectividade e alterações recentes. Faça cópia dos dados conforme seu procedimento antes de ações que possam alterar recursos. Firewall, backup e processo nessa modalidade são responsabilidade do operador.

Checklist para uma operação segura

  • Estado e instância confirmados antes de agir.
  • Automação e fila avaliadas antes do logout ou reconexão.
  • Uma única tentativa ativa por vez.
  • QR e códigos tratados como temporários e sensíveis.
  • Estado final confirmado antes de reabrir envios.
  • Teste feito para destino autorizado e controlado.
  • Falhas e eventos incertos preservados para reconciliação.
  • Mudanças registradas sem chaves e dados pessoais.

Reconexão manual ou automática

Uma rotina pode detectar desconexão e alertar operadores, mas automatizar o pareamento do usuário não é a mesma coisa que chamar uma ação de reconexão. O QR ou código ainda pode exigir confirmação no celular. Desenhe o fluxo para pausar envios, informar a equipe e aguardar a etapa humana quando necessária. Não faça loops que solicitem QR continuamente ou cliquem automaticamente em logout e reconnect.

Se o produto oferecer reconexão automática para falhas transitórias, siga a documentação e aplique limite de tentativas e backoff. Uma sequência infinita de tentativas consome recursos e pode ocultar um problema persistente. Após atingir o limite, abra uma ocorrência com o último estado e deixe o operador decidir o próximo passo.

Evite desconexões concorrentes

Em sistemas com vários operadores, serialize ações de reconexão e logout por instância. Duas pessoas podem solicitar códigos diferentes, alterar configuração ou iniciar pareamento simultâneo. Use um estado de manutenção e mostre quem iniciou a ação e quando. O backend deve conferir se a sessão ainda está na condição esperada antes de enviar um comando.

Uma confirmação extra para logout é apropriada porque a ação interrompe a conexão e exige novo pareamento. Explique quais filas e integrações podem ser afetadas. Depois de concluir, registre o novo estado e o responsável, mas não armazene código de conexão como evidência.

Indicadores de uma recuperação concluída

Considere o fluxo recuperado somente após consultar o estado final, validar que a aplicação usa a URL e o ID corretos e confirmar uma operação de baixo risco. Um QR escaneado ou uma resposta de reconnect não prova por si só que a sessão está pronta. Verifique o resultado na API e, se necessário, confirme um evento de conexão.

Retome os workers em lotes pequenos. Monitore respostas e fila durante alguns minutos e pause de novo se surgirem duplicatas ou nova desconexão. Para uma operação crítica, documente o horário de retomada e a pessoa responsável. Isso ajuda a correlacionar efeitos posteriores.

Revise o canal após troca de aparelho

Quando alguém troca o telefone principal ou remove dispositivos vinculados, verifique o estado da conta diretamente no aplicativo e siga os passos do WhatsApp. Não compartilhe códigos com suporte, colegas ou automações. Se houver suspeita de acesso não autorizado, proteja a conta primeiro e, depois, avalie sessões e credenciais relacionadas na StackZap.

Indicadores de recorrência

Se a mesma instância desconecta repetidamente, registre a frequência e correlacione com horário, alterações de rede, reinicializações, atualizações e eventos do celular. Uma reconexão pode restaurar serviço temporariamente sem corrigir a causa. No self-hosted, o operador examina host, banco, recursos e logs; no Cloud, abra ocorrência com a linha do tempo no widget do ambiente.

Roteiro de comunicação durante a indisponibilidade

Avise a equipe que mensagens podem ficar pendentes e informe qual canal alternativo está aprovado, se houver. Não peça que operadores tentem parear por conta própria. Designe uma pessoa para coordenar a reconexão e outra para acompanhar fila e callbacks. Depois que a sessão voltar, comunique o horário de retomada e revise se algum evento precisa de reconciliação.

Se o sistema atende clientes, prepare uma mensagem de contingência que não dependa do canal indisponível. Evite prometer prazo de retorno sem confirmação. Registre o incidente com início, impacto e resolução, e atualize o runbook quando surgir um passo novo. Essa comunicação reduz tentativas concorrentes e evita enviar mensagens duplicadas após a recuperação.

Proteja dados durante o diagnóstico

Capturas do painel podem mostrar nome de ambiente, telefone, QR ou dados de conta. Antes de compartilhar, corte ou oculte esses elementos. Em chamados, prefira ID da instância, status e horário. Um QR pode permitir pareamento enquanto válido; trate-o como credencial transitória e nunca inclua em documentação ou gravação.

Retome com fila controlada

Depois que o status indicar conexão, não libere toda a fila ao mesmo tempo. Comece com uma pequena quantidade de jobs recentes e válidos, verifique respostas e confirme que a aplicação está usando o número correto. Se o fluxo ficar estável, aumente gradualmente até o ritmo normal da operação. Jobs antigos devem ser avaliados pela validade do evento, não enviados apenas por estarem pendentes.

Registre quais jobs foram retomados e quais foram cancelados. Se alguns ficaram com resultado incerto antes da desconexão, consulte confirmações disponíveis ou encaminhe para reconciliação. Uma mensagem aceita pouco antes da queda não deve ser enviada novamente só porque o worker não recebeu o retorno.

Use reconexão como procedimento, não como palpite

Cada tentativa deve ter uma hipótese: por exemplo, sessão encerrou após remoção do dispositivo; então verifique o vínculo no celular e solicite novo pareamento. Se não houver hipótese, comece pela consulta de status e leitura do erro. Ações diferentes têm efeitos distintos: reconectar tenta restaurar a sessão, logout encerra o vínculo e remover instância pode alterar recursos. Confirme qual operação está executando.

Depois de duas tentativas sem avanço, pare e reúna evidências antes de continuar. Anote o estado exibido, horários, ação executada, versão e resultado HTTP. Essa pausa evita códigos repetidos e cria um relatório útil para suporte técnico.

Defina no runbook quem pode iniciar logout e reconexão, quem confirma o pareamento e quem retoma a fila. Uma autorização clara evita ações conflitantes durante incidentes e permite revisar depois o que aconteceu.

Inclua o link do artigo de pareamento e da referência técnica no runbook para que a equipe use instruções atualizadas. Anote a versão do procedimento e revise quando o painel ou os endpoints mudarem. Não copie QR ou códigos de pareamento para o documento: eles são temporários e específicos da tentativa.

Após uma recuperação, revise por que a sessão caiu e se uma mudança simples poderia evitar recorrência. Uma reconexão restaura a operação, mas não explica necessariamente a causa. Registre duração da indisponibilidade, fila afetada e prevenção adotada. Se o incidente envolver segurança da conta, priorize revisar dispositivos vinculados e acessos antes de reabrir automações.

Registre também o que foi comunicado aos atendentes e quando a fila voltou ao ritmo normal. Esse histórico ajuda a distinguir a reconexão técnica da retomada do serviço e orienta melhorias no procedimento.