Extensão Chrome (Manifest V3) que extrai contatos d 8000 e grupos, conversas/agenda e etiquetas do WhatsApp Web e salva em JSON.
- Abra
chrome://extensions. - Ative Modo do desenvolvedor (canto superior direito).
- Clique em Carregar sem compactação e selecione esta pasta.
- Abra
https://web.whatsapp.com, faça login e espere as conversas carregarem. - Clique no ícone da extensão.
Se você acabou de instalar/atualizar, recarregue a aba do WhatsApp Web (F5). A extensão também tenta se injetar sozinha, mas o F5 é o caminho garantido.
Recarregar a extensão em chrome://extensions não troca o wa-store.js que já está
rodando na aba do WhatsApp — ele vive no realm da página. Sempre: reload da extensão
e F5 na aba.
O protocolo é versionado para isso não virar um erro obscuro: VERSION em
src/content/wa-store.js e STORE_VERSION em src/popup/popup.js devem ser iguais.
Se divergirem, o popup avisa "aba desatualizada, aperte F5" em vez de estourar um
"Ação desconhecida". Suba as duas ao mudar o protocolo (ação nova, payload diferente).
Cada listener só responde enquanto for o dono da versão corrente
(window.__ZAP_EXTRACTOR_VERSION__), então script antigo em memória fica calado em vez de
disputar a resposta com o novo.
| Aba | O que faz |
|---|---|
| Conversas | Contatos = sua agenda com WhatsApp válido; Conversas = contatos das conversas individuais |
| Grupos | Busca por nome, seleção múltipla, extrai os participantes (com flag de admin) |
| Etiquetas | Contatos por etiqueta (só existe no WhatsApp Business) |
| Criar Grupo | Cria um grupo novo e adiciona os números em lotes (ver abaixo) |
| Opções | Filtros, opções de saída e "extrair todos os grupos" |
Entrada: um arquivo JSON (o exportado pela extensão, um array de strings ou texto com um número por linha) ou os grupos marcados na aba Grupos.
O fluxo é: normaliza e deduplica os números → valida (opcional) → cria o grupo com o primeiro lote → adiciona o resto em lotes com pausa → devolve um relatório.
A opção Simular vem ligada. Nesse modo nada é criado: você recebe o plano
(quantos participantes, quantos lotes, tempo estimado) e o relatório vai pra Downloads.
Desligue só quando o plano estiver do jeito que você quer.
Criar grupo em massa falha parcialmente e em silêncio, então o relatório separa:
| Campo | Significado |
|---|---|
added |
Entraram no grupo |
invited |
Não entraram. Privacidade do contato bloqueia adição direta (código 403) — só entram pelo invite_link |
already_in |
Já estavam no grupo |
no_whatsapp |
Sem WhatsApp (só preenchido com a validação ligada) |
failed |
Falharam, com o código e o motivo do WhatsApp |
over_limit |
Passaram do teto de 1024 participantes e foram ignorados |
invite_link é buscado no fim para você repassar a quem caiu em invited.
- Teto de 1024 participantes por grupo. O excedente vai pra
over_limit, não é tentado. Checar se cada número tem WhatsAppé uma requisição por número desconhecido, com 350 ms entre elas, e é agressivamente rate-limitado pelo WhatsApp. Deixe desligado para números vindos de grupos — eles obviamente já têm WhatsApp. Ligue só para listas de origem duvidosa.- Lote de 40 com 1500 ms de pausa são os padrões. Aumentar o lote e diminuir a pausa aumenta o risco de bloqueio.
- Adicionar gente em massa é o gatilho clássico de banimento — não pela automação em si, mas pelos reports de quem não pediu pra estar no grupo.
- Seu próprio número é removido da lista automaticamente.
Só o formato JSON está habilitado. CSV / Xlsx / VCard aparecem desabilitados no popup, prontos para serem ligados depois.
[
{
"country_code": "55",
"country_name": "BR",
"phone_number": "556799337256",
"formatted_phone": "+55 6799337256",
"is_my_contact": true,
"saved_name": "Acosta Gui",
"public_name": "Acosta Gui",
"is_business": false,
"is_admin": false,
"labels": []
}
]group_name é acrescentado no fim de cada registro quando a opção
"Incluir o nome do grupo em cada contato" está marcada. Em registros deduplicados que
apareceram em vários grupos, os nomes vêm separados por vírgula.
manifest.json
icons/ ícones gerados (16/32/48/128)
src/
content/
wa-store.js mundo MAIN — acessa o store interno do WhatsApp
bridge.js mundo ISOLATED — ponte postMessage <-> chrome.runtime
lib/
country-codes.js DDI -> ISO 3166-1 alpha-2
popup/
popup.html/.css/.js UI, filtros, dedupe e download
help.html página "Como usar"
Fluxo de uma extração:
popup.js --chrome.tabs.sendMessage--> bridge.js --postMessage--> wa-store.js
|
popup.js <----------- resposta ----------- bridge.js <--- postMessage --+
O wa-store.js roda no mesmo realm do app, então alcança o sistema de módulos do
WhatsApp (require('__debug').modulesMap) e busca as coleções ChatCollection,
ContactCollection, GroupMetadataCollection e LabelCollection. A resolução tem três
camadas de fallback: require pelo nome exato do módulo, match parcial nas chaves do
modulesMap e, por último, varredura dos módulos já carregados procurando o export
nomeado. Metadata de grupo que ainda não está em cache é buscada com
GroupMetadataCollection.find(wid).
Números de participantes em grupos novos vêm como @lid; nesse caso o telefone real é
lido de participant.phoneNumber / contact.phoneNumber.
Para criar grupo são usados WAWebQueryExistsJob (validação), WAWebGroupCreateJob
(sendCreateGroup), WAWebGroupModifyParticipantsJob (sendAddParticipants) e
WAWebGroupInviteJob (link de convite). A resposta por participante varia de formato
entre versões (array ou mapa por wid), então parseParticipants normaliza as duas formas;
se o ID do grupo não puder ser lido na resposta, a resposta crua vai para
raw_create_response no relatório em vez de a extensão fingir sucesso.
Enriquecimento (country_code, country_name, formatted_phone), filtros e dedupe
acontecem no popup — o content script devolve registros crus.
- Depende da estrutura interna do WhatsApp Web. Não é API pública; uma atualização grande do WhatsApp pode quebrar a resolução dos módulos.
- Códigos de área do Canadá não estão na tabela de DDI — números
+1canadenses saem comoUS. Os territórios do NANP (BS, BB, JM, DO, PR, TT, etc.) estão cobertos. - Grupos nunca abertos podem vir sem participantes; abra a conversa uma vez e extraia de novo. Os grupos que falharem são listados no alerta ao fim da extração.
- Etiquetas só existem em contas WhatsApp Business.
- Extrações muito grandes em sequência aumentam o risco de rate limit. Há uma pausa de 120 ms entre grupos.
Extração de contatos em massa pode violar os Termos de Serviço do WhatsApp, e usar esses dados para mensagens sem consentimento cai na LGPD. Use apenas com dados que você tem direito de tratar.