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:
- A sessão sobrevive ao servidor. Reinícios, atualizações da plataforma e trocas de máquina não apagam o pareamento.
- A sessão não fica exposta. Mesmo quem tivesse acesso ao armazenamento veria apenas dados cifrados, não as chaves que permitem agir em nome do número.
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:
reason | O que houve | Reconecta sozinha? |
|---|---|---|
transient | Queda de rede ou erro momentâneo do lado do WhatsApp | Sim, com espera crescente até abrir |
restart_required | O WhatsApp pediu uma conexão nova (normal logo depois do pareamento) | Sim, na hora |
replaced | Outro cliente assumiu a mesma sessão | Não: espera uma reconexão explícita |
logged_out | A sessão acabou do lado do WhatsApp (aparelho removido no celular, por exemplo) | Não: precisa de um QR code novo |
manual | Você desconectou pela API | Nã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ção | O 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 novo | Reabre 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ão | Sai 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.
Outros recursos
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.