WinZapp — Cliente de Desktop WhatsApp para Windows

Atenção: Este cliente ainda está em versão beta, portanto bugs podem ser esperados.

Versão atual: v0.21.0.0beta (Julho de 2026)
Repositório: https://github.com/gabrielhhaber/WinZapp_Python
Licença: GPLv3 — Software gratuito e de código aberto

ÍNDICE

Visão Geral
Público-Alvo
Principais Recursos
Arquitetura Técnica
Como Funciona Sob o Capô
Recursos de Acessibilidade
Segurança e Privacidade
Sistema de Som e Áudio
Gerenciamento de Mensagens
Suporte à Mídia
Sistema de Notificação
Atualizações Automáticas
Instalação e Uso
Personalização e Idiomas
Licença e Isenções de Responsabilidade
Links Úteis

1. Visão Geral

WinZapp é um cliente de desktop WhatsApp gratuito, de código aberto e auto-hospedado, projetado para Windows. Foi construído com um objetivo central: acessibilidade total para usuários cegos e com deficiência visual.

Integra-se com leitores de tela como NVDA, JAWS e Windows Narrator, com interface 100% navegável pelo teclado. Usa arquitetura híbrida: frontend em Python 3.13 + wxPython, combinado com servidor WPPConnect local (Node.js) como gateway do WhatsApp Web.

Tudo é executado localmente, sem servidores externos, nuvem ou intermediários. Suas conversas, contatos e mídias ficam em seu computador, com criptografia de ponta a ponta.

2. Público-Alvo

WinZapp é para você se:

Usa leitores de tela (NVDA, JAWS, Narrator) e precisa de um cliente WhatsApp que funcione corretamente com eles.
Prefere navegar usando o teclado — cada interação é controlada por teclado, com atalhos intuitivos e personalizáveis.
Valoriza sua privacidade e prefere software que rode 100% localmente.
Deseja um cliente de desktop WhatsApp completo com suporte a mensagens de texto, áudio, imagens, vídeos, documentos, adesivos, enquetes e mais.
É desenvolvedor e deseja contribuir para um projeto de código aberto que faz diferença na vida das pessoas.

3. Principais Recursos

3.1 Mensagens e Conversas

Envie e receba texto, áudio, imagens, vídeos, documentos, contatos e adesivos.
Mensagens de voz (PTT) com gravação, reprodução, pausa, descarte e controle de velocidade (1x, 1,5x, 2x).
Responder a mensagens citadas, encaminhar e editar mensagens enviadas.
Reações com emoji.
Enquetes — visualize e interaja.
Mensagens interativas (botões, listas, modelos).
@menções em grupos com preenchimento automático e sugestões.
Pesquisa dentro da conversa.
Separador de mensagens não lidas.

3.2 Gerenciamento de Bate-papo

Lista principal de conversas ordenada pela última mensagem.
Conversas arquivadas com indicador de não lidas.
Conversas fixadas e silenciadas.
Contador de não lidas sincronizado com o seu telefone.
Pesquisa de conversas e opção "Marcar tudo como lido".

3.3 Mídia e Anexos

Visualização de imagens embutidas com miniaturas.
Reprodução de áudio (OGG Opus, AAC) via biblioteca BASS.
Reprodução de vídeo.
Download de mídia diretamente no aplicativo.
Envio de arquivos como documentos, imagens, vídeos e áudio.
Visualizar status/histórias de contato (24h).
Envio de atualizações de status de texto, imagem e vídeo.

3.4 Contatos

Sincronização automática de contatos salvos.
Resolução de nomes via pushName do WhatsApp e lista telefônica.
Suporte a @lid JID (dispositivos vinculados) — resolve identificadores internos para números reais.
Cache local de mapeamentos @lid → telefone com criptografia.
Intercambialidade brasileira de 9 dígitos (55XX9YYYYYYYY equivale a 55XXYYYYYYYY).
Pesquisa de contatos salvos, nova conversa e criação de novos contatos.

3.5 Grupos

Criação de grupo, adicionar e remover participantes.
Exibição do nome do participante em cada mensagem.
@menções individuais e @todos.
Informações do grupo (descrição, participantes, foto).

3.6 Presença Online

Indicadores de status online/offline para contatos.
Indicadores de "Digitando…" / "Gravando áudio…".
Última visualização formatada por extenso (hoje, ontem, data completa).
Envia presença "disponível" quando a janela está focada.

3.7 Chamadas de Áudio e Vídeo

Não disponível.

3.8 Sistema de Notificação

Notificações nativas do Windows 11 com resposta rápida integrada.
Sons personalizáveis por conversa e por tipo (privado, grupo).
10 tons de alerta diferentes.
Notificações em primeiro plano e segundo plano.
Coalescência de notificações (apenas uma por vez, sem empilhamento).
Suprime o som padrão do Windows e reproduz o som personalizado.

3.9 Sistema de Som

Sistema composto por pacotes de som.
Pacote padrão com mais de 20 eventos de som.
Importação de pacotes personalizados.
Ativação/desativação individual por evento.
Pré-visualização do som antes de selecionar.
Suporte para arquivos OGG Vorbis e plugins BASS.

3.10 Atalhos de Teclado

Navegação completa pelo teclado com atalhos intuitivos.
Tecla de atalho global personalizável (Win+W, Ctrl+Alt+W, etc.).
Marcadores de mensagens (Ctrl+0..9 / Ctrl+Shift+0..9).
Alt+1: Conversas | Alt+2: Arquivadas | Alt+3: Status | Alt+4/Ctrl+,: Configurações
Ctrl+Shift+F: Pesquisar | Ctrl+Shift+D: Dados da conversa
Ctrl+Shift+A: Anexar mídia | Ctrl+Shift+S: Salvar mídia como
Ctrl+Shift+Alt+M: Marcar tudo como lido
Ctrl+Alt+Shift+D: Desconectar | Ctrl+Alt+Shift+Q: Sair | Ctrl+Alt+Shift+O: Offline
F5: Sincronizar tudo | F1: Atalhos de teclado
Setas: Navegar mensagens | Enter: Abrir conversa/Ação | Delete: Excluir
Ctrl+C: Copiar | Espaço: Reproduzir/pausar áudio
Ctrl+E: Editar | Ctrl+R: Responder | Ctrl+Shift+R: Encaminhar
Ctrl+Shift+E: Redigir mensagem de voz
Tab/Shift+Tab: Navegar entre controles
Atalhos de moderação de grupo (promover, remover)

3.11 Atualizações Automáticas

Verificação via GitHub Releases API.
Download ZIP em segundo plano com barra de progresso.
Verificação de integridade SHA256.
Instalação automática via script em lote (aguarda fechamento, elimina processos residuais, copia arquivos e reinicia).
Verificações independentes de atualização do WPPConnect.
Opções "Forçar atualização" e "Reinstalar do ZIP" no menu Ajuda.

3.12 Modo Offline

Modo offline manual e automático (detectado quando o WhatsApp desconecta).
Reconexão automática silenciosa com indicação na barra de status.
Fila de mensagens offline que são entregues quando a conexão retornar.

3.13 Bandeja do Sistema

Ícone com indicador visual de status (conectado, desconectado, sincronização).
Menu de contexto: restaurar, modo offline, sair.
Minimizar para a bandeja ao fechar.
Inicialização automática com o Windows (opcional).

3.14 Internacionalização (i18n)

Idiomas: Português do Brasil (padrão), Inglês (EUA), Espanhol, Português (Portugal).
Sistema de tradução baseado em JSON com cache.
Formatação de números localizada.

4. Arquitetura Técnica

4.1 Processo Python (Cliente Gráfico)

Linguagem: Python 3.13 | GUI: wxPython 4.2.4
Acessibilidade: accessible_output2 (NVDA, JAWS, Narrator)
Áudio: sound_lib (BASS), PyAudio | Rede: python-socketio, requests
BD: aiosqlite (SQLite assíncrono + Fernet) | Notificações: Windows Toasts (WinRT/COM)
Threading: ThreadPoolExecutor

Cerca de 11.700 linhas em client/main.py lidando com toda a lógica de negócios, estado de bate-papo, WebSocket, API HTTP, som, notificações, menus e atualizações.

4.2 Processo Node.js (Servidor WPPConnect)

Repositório: wppconnect-team/wppconnect-server
Função: Gateway WhatsApp Web via Puppeteer
Instalação: Automatizada por setup_api.py | Porta padrão: 6300
Comunicação: API REST (HTTP) + Socket.IO (WebSocket)
Sessão: Chrome headless gerenciado por Puppeteer

4.3 Arquitetura de Dados

SQLite em modo WAL para persistência local.
Colunas indexadas (jid, timestamp) em texto simples.
Cargas úteis (message_json, last_message_json) criptografadas via Fernet.
Chave única por instalação (secret.key).
Ponte assíncrona (DatabaseBridge) com timeout de 20 segundos.
Pool de threads (4 workers) para operações em segundo plano.

4.4 Pipeline de Mensagens

WPPConnect recebe mensagem do WhatsApp Web via Puppeteer.
Encaminha via Socket.IO como evento messages.upsert.
WebSocketClient (Python) normaliza a carga útil.
MainWindow.on_new_message() desduplica @lid, atualiza estado, agenda persistência e dispara notificação.
DatabaseBridge salva de forma assíncrona no SQLite.
Interface atualizada via wx.CallAfter na thread principal.

5. Como Funciona Sob o Capô

5.1 Inicialização

main.py verifica DLLs (bassopus, etc.), carrega configurações, sons e idioma.
Verifica sessão emparelhada existente. Se não, mostra QR Code ou código de emparelhamento.
Se sim: recupera token, conecta WebSocket, prepara sincronização.
Inicializa interface e inicia verificações de atualização.

5.2 Emparelhamento

Dois modos: QR Code ou Código Numérico.
Suporte para ligação telefônica (país + código de área + número).
WPPConnect cria sessão headless do Chrome.
Socket.IO recebe eventos: qrCode, phoneCode, session-logged-in.
Ao concluir: salva token criptografado e inicia sincronização.

5.3 Sincronização Inicial

Busca lista de bate-papos via API REST, contatos salvos e mensagens (paginado, 200 por vez).
Resolve @lid JIDs para números de telefone.
Carrega na memória, persiste no SQLite e atualiza a interface.

5.4 Mensagem de Saída

Usuário digita e pressiona Enter.
ConversationsPanel cria mensagem virtual "pendente".
MessageQueue enfileira e tenta envio imediato.
HTTP POST para WPPConnect /api/session/send-message.
Sucesso: retorna ID real, registra em _own_sent_ids.
Interface atualiza status de "enviando" para "enviado".
Eco do WebSocket (fromMe = True) é ignorado via _own_sent_ids.
Atualizações de entrega/leitura chegam via messages.update.

5.5 Retentativa Inteligente

Falha "Desconectado": mensagem permanece na fila.
Timeout/queda: tratado como "ambíguo" (sem retentativa, o WhatsApp pode ter aceitado).
Falha definitiva do servidor: tenta até 4 vezes.
Após tentativas exaustivas: notifica o usuário.

5.6 Resolução JID

@s.whatsapp.net: formato canônico de telefone.
@c.us: formato legado, normalizado para @s.whatsapp.net.
@lid: identificador de dispositivo vinculado, resolvido via /contact/fetchProfile.
@g.us: JID de grupo. @broadcast: status/histórias. @newsletter: canais (ignorados).

6. Recursos de Acessibilidade

A acessibilidade é o principal diferencial do WinZapp, não um recurso secundário.

6.1 Interface Navegável por Teclado

Todos os botões, menus, listas e campos acessíveis via Tab e atalhos. Nenhuma ação requer mouse.

6.2 Compatibilidade com Leitores de Tela

NVDA (suporte completo), JAWS, Narrator do Windows. Via biblioteca accessible_output2.

6.3 Proteções do Leitor de Tela

Protetores de foco virtuais evitam gagueira e loops ao reconstruir listas.
Mutações em lote dentro de Freeze()/Thaw() para um único evento de acessibilidade.
Itens de lista sempre resolvem nomes legíveis, nunca JIDs brutos.

6.4 Classes Personalizadas e Controles Nativos

Classes: AccessibleSearchInConversation, AccessibleMessagesListControl, AccessibleRecordVoiceMessage, AccessibleAudioSlider, etc.
Controles wxPython nativos (wx.ListCtrl, wx.TextCtrl, menus padrão). Sem controles personalizados.

7. Segurança e Privacidade

7.1 Criptografia em Repouso

Cargas de mensagens criptografadas com Fernet (AES) em SQLite.
Chave única por instalação (secret.key).
Token de sessão criptografado (não em texto simples).
Criptografia portátil: copie a pasta de dados para outro PC e o token descriptografa normalmente.

7.2 Confiança Zero em Servidores Externos

Tudo funciona localmente. Servidor WPPConnect em localhost:6300.
Criptografia de ponta a ponta do WhatsApp aplicada normalmente.

7.3 Limpeza de Dados

"Limpar dados locais" ao sair/dispositivo removido. Evita vazamento entre contas.

7.4 Segurança do Processo

Redução de privilégios: Node.js executado com privilégios reduzidos se o app for admin (API Windows Safer).
Mutex de instância única. Não funciona como serviço, não expõe portas à rede.

8. Sistema de Som e Áudio

8.1 Sistema de Som (BASS)

Mecanismo baseado em BASS (sound_lib). Plugins: bassopus (OGG Opus), bass_aac (AAC).
Streaming com controle de tempo para ajuste de velocidade. Som em canal separado.

8.2 Pacotes de Som

Pacotes em cliente/sons/subpastas com manifesto .pack.json.
Pacote padrão com mais de 25 eventos. Importação de pacotes personalizados com validação.

8.3 Eventos de Som (18 eventos)

inicialização, erro, qrcode_loaded, wait_pairing, pairing_code_updated, conectado, sincronizando, sync_complete, modo_offline, voicemsg_startrecording, voicemsg_pauserecording, voicemsg_discard, voicemsg_send, mensagem_atual, mensagem_foreground, mensagem_background, mensagem_enviada

8.4 Tons de Alerta (10 tons)

Alerta-01.ogg até Alerta-10.ogg. Configurável globalmente e por conversa.

8.5 Gravação de Áudio

Gravação via PyAudio (callback em thread separado). Pausar/retomar.
Conversão WAV → OGG via ffmpeg. Cache em voice_messages/. Descarte de gravação.

9. Gerenciamento de Mensagens

9.1 Banco de Dados SQLite

Tabelas: chats, messages, contacts, lid_mappings, unresolvable_lids, status_updates, system_metadata.
Modo WAL. Paginação: 200 mensagens por bate-papo. Limite de 1.000 mensagens na RAM por bate-papo.
Status de entrega: -1 = falha, 0 = pendente, 2 = enviado, 3 = entregue, 4 = lido, 5 = reproduzido.

9.2 Fila de Mensagens

Thread de trabalho único para envio sequencial. Ativação imediata.
Retentativa a cada 3 segundos em caso de falha. Suspensão automática no modo offline.
Prevenção de duplicatas via _own_sent_ids.

9.3 Histórico e Sincronização

Ressincronização completa (F5). Sincronização incremental na reconexão.
Preenchimento de mensagens (paginação) ao rolar para cima.
Mensagens históricas com flag isMdHistoryMsg tratadas separadamente.

10. Suporte à Mídia

10.1 Tipos Suportados

Imagens (JPEG, PNG, GIF, WebP), Vídeos (MP4), Áudio (OGG Opus, AAC), Documentos (PDF, DOCX, XLSX), Adesivos, Contatos (vCard), Localizações, Enquetes.

10.2 Player de Áudio

Reproduzir/pausar, avançar/retroceder. Velocidade: 1x, 1,5x, 2x.
Controle deslizante com feedback via teclado. Encadeamento automático. Posição salva ao trocar de conversa.

10.3 Download de Mídia

Download via API WPPConnect (/get-media-by-message). Progresso exibido na interface.
Salvar com "Salvar como". Tratamento de mídia expirada (HTTP 403/410).

11. Sistema de Notificação

11.1 Notificações do Sistema (Windows 11)

Windows Toasts (WinRT/COM). AUMID "WinZapp" registrado.
Resposta rápida integrada. Notificação única por vez (coalescência). Sons personalizados.

11.2 Formatação

Título: nome do contato ou "Participante do Grupo".
Corpo: texto ou descrição do tipo de mídia (ex.: "Mensagem de voz (0:35)", "Foto: legenda").
Prefixos: "Respondeu a você", "Mencionou você", "Mencionou todos". Sufixo: contador de não lidas.

11.3 Acionamento

Primeiro plano: anúncio via accessible_output2. Segundo plano: notificação do sistema + som.
Silencioso se o bate-papo estiver silenciado. Som de segundo plano configurável por conversa.

12. Atualizações Automáticas

12.1 Verificador do WinZapp

Consulta a API de Releases do GitHub. Comparação de versões com suporte a pré-lançamento.
Download ZIP com barra de progresso. Verificação SHA256.
Instalação via script em lote: aguarda saída do PID, elimina processos na porta 6300, copia arquivos e reinicia.

12.2 Verificador do WPPConnect

Verificação independente da versão do servidor. Comparação SemVer.
Reinstalação sem Git (via download ZIP). Opção "Forçar reinstalação" no menu.

12.3 CI/CD

GitHub Actions para builds automatizados. Cache de dependências (pip, node_modules, MSYS2).
Geração de SHA256. Artefatos: WinZappInstaller.exe e WinZapp.zip.

13. Instalação e Uso

13.1 Usuário Final

Baixe WinZappInstaller.exe na página de Releases. Execute o instalador.
Ou use a versão portátil WinZapp.zip (extrair e executar).

13.2 Desenvolvedor

git clone https://github.com/gabrielhhaber/WinZapp_Python.git
python -m venv venv
pip install -r requirements.txt
python setup_api.py
cd cliente && python main.py

13.3 Build (Empacotamento)

python build.py (cria instalador + ZIP portátil).
Requer: PyInstaller, GCC/windres (MSYS2), Node.js portátil, WPPConnect pré-compilado.

13.4 Primeira Utilização

Escolha seu idioma (pt-BR, en-US, es-ES, pt-PT).
Aceite os termos de serviço.
Configure inicialização automática (opcional).
Configure tecla de atalho global (opcional).
Escolha API local (recomendada) ou personalizada/remota.
Conecte-se via QR Code ou código numérico.
Pronto! Suas conversas serão sincronizadas.

14. Personalização e Idiomas

14.1 Idiomas Disponíveis

Português Brasileiro (pt-BR) — padrão | Inglês (EUA) (en-US) | Espanhol (es-ES) | Português (Portugal) (pt-PT)
Sistema extensível: crie um arquivo JSON + entrada em idioma_map.json.

14.2 Configurações (Arquivo > Configurações)

Geral: idioma, inicialização automática, tecla de atalho global.
Som: pacote ativo, eventos alternáveis individualmente.
Tons de alerta: tom padrão para privado e grupo, pré-visualização.
Notificações: controle do sistema. Áudio: velocidade padrão (1x, 1,5x, 2x).
API: servidor WPPConnect, porta, chave. Sobre: versões do app e servidor.

14.3 Informações da Conversa (Ctrl+Shift+D)

Nome, foto do perfil, descrição do grupo, participantes, som personalizado, opção de silenciar.

14.4 Tecla de Atalho Global

Configurável (qualquer combinação com Ctrl, Alt, Shift, Win).
Autorrecuperação: registra-se novamente a cada 5 minutos para evitar perda silenciosa.

15. Licença e Isenções de Responsabilidade

WinZapp é licenciado sob a Licença Pública Geral GNU v3 (GPLv3).

Você pode: usar, estudar, modificar e distribuir o software e cópias modificadas.

Condições: manter a licença GPLv3 em todas as cópias e fornecer o código-fonte de versões modificadas. Não há garantia de qualquer tipo.

Aviso Legal: WinZapp depende de engenharia reversa do protocolo WhatsApp Web. O uso é por sua conta e risco. Este repositório não é afiliado, mantido ou patrocinado pela Meta Platforms, Inc. (Facebook/WhatsApp).

16. Links Úteis

Repositório: https://github.com/gabrielhhaber/WinZapp_Python
Releases (downloads): https://github.com/gabrielhhaber/WinZapp_Python/releases
WPPConnect: https://github.com/wppconnect-team/wppconnect-server
accessible_output2: https://github.com/accessibleapps/accessible_output2
wxPython: https://www.wxpython.org/
NVDA: https://www.nvaccess.org/
GPLv3: https://www.gnu.org/licenses/gpl-3.0.html

WinZap, um cliente de código aberto para WhatsApp