Pular para o conteúdo
apiwpp
Recurso

Sessão persistente: o número continua conectado depois de reinícios

A sessão do WhatsApp fica salva e criptografada na apiwpp: reinícios e atualizações não pedem novo QR code, e o celular pode ficar desligado.

Atualizado em

Quem já montou uma integração com o WhatsApp Web conhece o problema: o servidor reinicia, o contêiner é recriado, e alguém precisa pegar o celular para escanear o QR code de novo. Numa operação com vários números, isso vira rotina de suporte e deixa mensagens paradas até alguém perceber.

Na apiwpp, o pareamento acontece uma vez. Depois que o número escaneia o QR code (ou digita o código de pareamento), a sessão fica guardada e é reaproveitada em cada reconexão. Você conecta o número e segue trabalhando.

A sessão fica salva e criptografada

Uma conexão da apiwpp é um aparelho conectado do número, como o WhatsApp Web. Para funcionar sem o celular, esse aparelho precisa guardar as chaves da sessão. A apiwpp armazena essas chaves no banco de dados, criptografadas em repouso, e não em arquivos soltos no disco de um servidor.

Isso tem duas consequências práticas:

Reinícios e atualizações não pedem QR code

Quando a conexão cai, a apiwpp decide se deve reconectar sozinha e avisa o seu sistema pelo webhook connection.status. Cada fechamento traz o motivo (reason) e o campo willReconnect:

reasonO que houveReconecta sozinha?
transientQueda de rede ou erro momentâneo do lado do WhatsAppSim, com espera crescente até abrir
restart_requiredO WhatsApp pediu uma conexão nova (normal logo depois do pareamento)Sim, na hora
replacedOutro cliente assumiu a mesma sessãoNão: espera uma reconexão explícita
logged_outA sessão acabou do lado do WhatsApp (aparelho removido no celular, por exemplo)Não: precisa de um QR code novo
manualVocê desconectou pela APINão: espera você reconectar

Nos casos comuns (rede instável, reinício, atualização), a reconexão usa a sessão guardada e o próximo evento é um connection.status com status: open. Nada de QR code novo, nada de pedir ajuda ao dono do número.

Uma dica para os alertas do seu sistema: avise alguém na hora quando chegar um fechamento com willReconnect: false. Quando for true, espere um pouco e só avise se nenhum open chegar, porque a reconexão costuma resolver sozinha.

O celular pode ficar desligado

Como aparelho conectado, a conexão da apiwpp não depende do celular para enviar e receber mensagens. O telefone pode ficar sem bateria, sem internet ou guardado numa gaveta, e o número continua atendendo pela API.

Isso muda a forma de operar números de empresa: não é preciso manter um celular ligado na tomada, ao lado de um computador, só para a integração não cair. O celular continua útil para o que ele faz de melhor, como um atendente responder uma conversa à mão, e essas mensagens podem até chegar ao seu sistema pelo evento opcional message.outgoing.

Desconectar, reconectar, sair e excluir

Nem toda interrupção é igual, e a API deixa claro o que acontece com a sessão em cada caso:

AçãoO que acontece com a sessão
Desconectar (POST /connections/{id}/disconnect)A conexão fecha e a sessão fica guardada: reconecte sem QR code
Conectar de novoReabre com a sessão guardada, ou começa um pareamento se não houver sessão
Logout (POST /connections/{id}/logout)Sai do WhatsApp e apaga a sessão: o próximo pareamento pede um QR code novo
Excluir a conexãoSai do WhatsApp e remove a conexão com a sessão, os templates e o histórico, sem volta

Use o desconectar para pausar um número por um tempo, e o logout quando quiser trocar o número de uma conexão. Um cuidado: depois de um logout, o novo pareamento recomeça o aquecimento de 14 dias e zera a lista de contatos conhecidos.

Fatura atrasada não apaga o pareamento

A sessão também é preservada na cobrança. Se uma fatura atrasar, a conta tem 5 dias de carência. Depois disso, a organização é suspensa: os números são desconectados, mas as sessões ficam guardadas. Assim que o pagamento é confirmado, os números voltam sem precisar de um QR code novo. Durante a suspensão, os logs e as faturas continuam disponíveis para consulta.

Na prática, um atraso no financeiro não obriga ninguém a pedir aos seus clientes que escaneiem o QR code de novo. Os detalhes de planos e pagamento estão em preços.

Acompanhe a saúde de cada conexão

Além do webhook, GET /connections lista as conexões dos seus projetos com o status atual, e o painel mostra o estado de cada número. A página de status pública acompanha a plataforma como um todo, com um teste que envia mensagens reais entre dois números a cada 10 minutos.

Para começar do zero, veja como funciona a conexão por QR code ou código de pareamento. Para saber como os eventos chegam ao seu servidor, veja os webhooks assinados, ou leia o tutorial sobre como conectar um número à API.

Perguntas frequentes

Vou precisar escanear o QR code de novo quando vocês atualizarem a plataforma?

Não. A sessão fica salva e criptografada no banco de dados, então reinícios, atualizações e quedas de rede reconectam o número com a sessão guardada. Um QR code novo só é necessário se a sessão acabar do lado do WhatsApp, por exemplo quando o aparelho é removido no celular, ou depois de um logout.

O celular precisa ficar ligado e com internet?

Não. A apiwpp funciona como um aparelho conectado, igual ao WhatsApp Web, e envia e recebe mensagens mesmo com o celular desligado ou sem conexão.

Qual a diferença entre desconectar e fazer logout?

Desconectar fecha a conexão e guarda a sessão, para reconectar depois sem QR code. Logout sai do WhatsApp e apaga a sessão; use quando quiser conectar outro número na mesma conexão.

O que acontece com os meus números se a fatura atrasar?

Há 5 dias de carência. Depois, os números são desconectados com as sessões guardadas e voltam sem QR code novo assim que o pagamento é confirmado.

Todos: Recursos →

Cada número entra na apiwpp como um aparelho conectado, igual ao WhatsApp Web: escaneie o QR code ou digite um código de 8 caracteres no celular e acompanhe o status pela API e pelo webhook connection.status.

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.

Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.