Documentação do ZPE Desktop

Tudo o que você precisa para colocar o ZPE Desktop em operação: instalação em cada sistema, pareamento com o WhatsApp, vínculo seguro com o Luva CRM e o dia a dia de campanhas, recibos e múltiplas instâncias.

Visão geral

O ZPE Desktop é um cliente WhatsApp para computador construído sobre o whatsmeow. Ele mantém a sessão do WhatsApp conectada localmente — o celular não precisa ficar ligado — e se integra ao Luva CRM em duas vias:

• CRM → Desktop: campanhas e envios chegam como lotes que exigem confirmação humana local antes de qualquer mensagem sair;
• Desktop → CRM: histórico, mensagens novas, mídia e recibos são sincronizados para a caixa de entrada do CRM com deduplicação garantida.

Todo o estado local (conversas, mensagens, fila, mídia) fica em SQLite no perfil do usuário. Credenciais do CRM ficam no cofre de senhas do sistema operacional.

Instalação

Baixe o pacote do seu sistema na página de download e selecione o guia abaixo. Nenhum sistema exige ferramentas de desenvolvimento — os pacotes são autossuficientes.

shasum -a 256 ~/Downloads/zpe-desktop-macos-universal.zip
# compare a saída com o SHA-256 publicado no release

certutil -hashfile "%USERPROFILE%\Downloads\zpe-desktop-windows-installer.exe" SHA256
# compare a saída com o SHA-256 publicado no release

# pré-requisitos: Go 1.25+, Node 20+, Wails v2, libwebkit2gtk-4.1-dev
git clone https://github.com/3lados/zpe-desktop
cd zpe-desktop
wails build -tags webkit2_41
# artefato: build/bin/zpe-desktop

Parear com o WhatsApp

1. Abra o ZPE Desktop. A tela inicial exibe um QR code.
2. No celular, abra o WhatsApp → Configurações → Aparelhos conectados → Conectar um aparelho.
3. Escaneie o QR code exibido no computador.
4. Aguarde a mensagem “Conectado! Carregando...” — o histórico inicial sincroniza automaticamente.

Depois do pareamento, a sessão fica salva localmente: fechar e abrir o aplicativo não exige novo QR. O celular pode ficar desligado — o desktop mantém a conexão por conta própria.

Vincular ao Luva CRM

O vínculo usa um código de autorização de uso único gerado pelo CRM:

1. No Luva CRM, acesse Configurações → Instâncias WhatsApp e crie uma instância do tipo “WhatsApp Desktop (ZPE)”.
2. Na instância criada, gere o código de autorização — o CRM exibe o código copiável e um QR equivalente, com validade curta.
3. No ZPE Desktop, abra o cartão LUVA CRM e informe a origem do CRM (ex.: https://app2.luvacrm.com.br) e o código.
4. Confirme a conexão com a segunda ação explícita — o código nunca é enviado automaticamente.

Propriedades do vínculo:

• o código é de uso único e expira — reutilização falha fechado;
• o dispositivo fica vinculado exatamente a um tenant e uma instância; não alcança outras instâncias do mesmo tenant;
• o token do dispositivo fica no cofre do sistema (Keychain, Credential Manager, Secret Service);
• revogar o dispositivo no CRM derruba a conexão e bloqueia trabalho pendente.

Operação diária

Campanhas e confirmação humana

Quando o CRM despacha uma campanha para a sua instância, o ZPE Desktop recebe um lote e o persiste localmente antes de qualquer notificação. Nada é enviado sem a sua revisão:

1. O aplicativo sinaliza “trabalho disponível” no painel Envios do CRM.
2. Abra o lote e revise destinatários e conteúdo.
3. Confirme o envio — a confirmação é por lote, explícita, e não é herdada por lotes futuros.
4. O desktop envia com pacing e reporta cada item ao CRM (enviado, falhou, recibos).

Envios são idempotentes: reinícios ou reconexões não duplicam mensagens — cada item tem identidade estável e um journal local impede repetição.

Recibos e status

O status nunca regride: um recibo atrasado de prioridade menor não “des-lê” uma mensagem. Em Dados da mensagem você vê a timeline completa — incluindo, em grupos, o participante de cada recibo.

Multi-instância

Abrindo o ZPE Desktop normalmente, o próprio aplicativo gerencia várias instâncias em uma única janela:

• a coluna lateral esquerda alterna entre instâncias;
• o botão + cria um perfil novo (QR próprio, CRM próprio);
• eventos de instâncias em segundo plano viram um badge numérico no ícone da instância;
• cada instância tem bancos, mídia, fila e sessão totalmente isolados, podendo apontar até para origens diferentes do CRM.

O modo antigo — uma janela por perfil — continua suportado via linha de comando:

# macOS
open -n "/Applications/zpe-desktop.app" --args --profile chip-01
# Linux / Windows
zpe-desktop --profile chip-01

Solução de problemas

“Não foi possível conectar” ao escanear o QR

Sintoma clássico de QR vencido. Versões atuais renovam o código automaticamente; se a tela ficar sem QR por mais de ~30 segundos, use o botão Tentar novamente.

Instância aparece “desconectada” no CRM

1. Confirme que o ZPE Desktop está aberto e o WhatsApp conectado (bolinha verde na instância);
2. Verifique o cartão LUVA CRM — estado deve ser conectado;
3. Se estiver revogado, gere um novo código de autorização no CRM e refaça o vínculo.

Campanha não chega ao desktop

• O relay entrega trabalho apenas com o vínculo ativo e a instância correta — confira no CRM se a campanha aponta para a instância desta máquina;
• Lotes já reservados por outro dispositivo não são re-entregues até liberação.

Ícone genérico no Alt+Tab (Linux)

Instale o arquivo .desktop com StartupWMClass=zpe-desktop e os ícones hicolor conforme o guia do Linux; depois relogue a sessão.

macOS bloqueou o aplicativo

Fluxo completo na seção do macOS: botão direito → Abrir; se não houver botão, Ajustes do Sistema → Privacidade e Segurança → Abrir Mesmo Assim.

Onde ficam meus dados?

Perfis adicionais vivem em profiles/<nome>/ dentro do diretório de dados. Excluir uma instância pelo aplicativo remove os dados locais e, quando vinculada, também a instância correspondente no CRM.