Sessões

Um canal é uma linha no banco de dados do nosso sistema. Uma sessão é a conexão de WhatsApp viva que o sustenta. Enquanto o canal está connected, os dois são 1:1 — mas têm ciclos de vida diferentes.

O que é uma sessão

Por baixo dos panos, cada canal conectado segura o estado criptográfico que torna a conexão "sua" — as mesmas primitivas que o cliente oficial do WhatsApp Web usa. A gente persiste esse estado do lado do gateway para que um reinício de processo consiga retomar o canal sem forçar um novo scan de QR.

Você não gerencia nada disso diretamente. Da perspectiva da sua aplicação, existe só o canal: ele está connected ou não.

Por que sessões podem cair

Três coisas tiram um canal de connected:

1. Oscilação de rede. A conexão cai, o gateway transiciona o canal para reconnecting, e retoma a partir do estado persistido. Geralmente invisível.

2. O usuário revoga a sessão. Causas comuns:

   • O usuário deslogou pela tela de Aparelhos conectados do celular.
   • O usuário entrou por outro cliente do WhatsApp Web e a plataforma rotacionou as chaves.

   Quando isso acontece, o estado persistido é invalidado, o canal vai para disconnected, e um novo scan de QR é necessário.

3. Reinício do gateway. O estado persistido sobrevive em disco, então o próximo boot retoma sem emendas. Quaisquer envios de saída em andamento entram na fila e retomam na volta — veja Conceitos → Webhooks → Retentativas para o que isso significa na prática.

O que você vai ver

O dashboard assina o /v1/events e renderiza essas transições ao vivo. Um canal preso em reconnecting por mais de ~30 segundos é incomum e mostra um banner para você notar sem precisar consultar. Sua aplicação recebe a mesma informação pelos webhooks channel.connected e channel.disconnected.