Uma CLI local para operações seguras com Evolution API 2.3.7, feita para reduzir a saída e o contexto consumido por agentes de IA. A versão 0.4.0 mantém os comandos focados e acrescenta o catálogo integral do perfil para operações avançadas sem abrir despacho HTTP arbitrário.
Medição autorizada em 2026-08-18, sobre a mesma operação instance.list com
oito instâncias. Nenhum nome, telefone, URL, estado individual ou dado bruto é
publicado.
| Saída | Caracteres | Resultado |
|---|---|---|
| Completa compacta | 11.160 | Referência legada |
agent batch com view: "summary" |
157 | 11.003 caracteres a menos |
| Redução | 98,6% | Saída cerca de 71,1x menor |
Metodologia, cálculo e limites. Caracteres são a medida reproduzível desta comparação. Tokens e custo exato variam conforme o modelo, tokenizador e preço usados pelo agente.
Requer Python 3.11 ou posterior.
py -3 -m pip install -e .
ad3-evolution --mode demo doctor
ad3-evolution capabilities
ad3-evolution api catalog --prefix message.O modo demo é offline. Para remote ou local, configure ambiente ou .env
local; nunca passe chave de API pela linha de comando.
AD3_EVOLUTION_MODE=remote
EVOLUTION_BASE_URL=http://127.0.0.1:8080
EVOLUTION_API_KEY=definida-no-ambiente-local
api catalog expõe as 177 operações de cliente do tag oficial 2.3.7, com
método, rota, parâmetros de caminho, suporte a upload/download e modo de
execução. Callbacks de entrada, Manager e métricas pertencem ao servidor e não
aparecem como comandos de cliente. Duas rotas que devolvem credenciais ficam
catalogadas como restricted, mas não são despachadas pela CLI.
Use api read somente para operações marcadas como read; ele aceita payload
e query como objeto JSON. O único item marcado como download grava a mídia
Base64 diretamente em arquivo, sem expor o conteúdo no terminal. Toda operação
marcada como plan, inclusive envio, configuração, exclusão e rotas de baixo
nível, gera um plano hashado e só sai após apply com o mesmo ID.
ad3-evolution api read --operation chat.find-contacts --instance aula --payload-file .\find-contacts.json
ad3-evolution api download --operation chat.get-base64-from-media-message --instance aula --payload-file .\media.json --output-file .\media.bin
ad3-evolution api plan --operation message.send-poll --instance aula --payload-file .\poll.json
ad3-evolution apply --plan-id ID --confirm IDRotas com identificador adicional usam --param NOME=VALOR. Para os cinco
endpoints de mídia multipart, passe --file; o plano registra hash e tamanho
do arquivo e recusa a aplicação se o arquivo mudar. Prefira --payload-file
UTF-8 para dados sensíveis, pois --payload fica exposto ao histórico do
shell. Respostas com Base64, token, chave, senha ou autorização são redigidas
antes de qualquer saída.
A redação mascara número de telefone, inclusive o JID individual e o @lid, e
também o JID de grupo no formato legado <telefone>-<timestamp>@g.us, que
carrega o número de quem criou o grupo. O JID de grupo moderno, só dígitos, é um
identificador opaco e sai inteiro: ele é o que chat list devolve e o que
chat messages exige, então mascará-lo quebraria a própria leitura.
Leituras que varrem a conta inteira têm um piso de timeout próprio — 90s para
group list e 30s para as leituras de chat —, porque numa conta com muitos
grupos fetchAllGroups não cabe nos 10s padrão. EVOLUTION_TIMEOUT maior que o
piso continua prevalecendo. Falha de rede, rota ou instância chega ao operador
com a causa já sanitizada, em vez de uma mensagem genérica.
Os payloads continuam iguais aos do contrato oficial. O catálogo deliberadamente não cria uma segunda sintaxe por endpoint: isso mantém a cobertura completa sem inventar campos nem permitir URL ou método arbitrários.
capabilities descreve deterministicamente o protocolo
ad3-evolution.agent/v1. O lote aceita um objeto JSON, array JSON ou JSONL
UTF-8, com até 50 itens e 1 MiB. A allowlist é somente leitura; erros de um item
não impedem as respostas dos demais e resultam em exit 2.
@'
{"id":"health","op":"doctor","args":{}}
{"id":"instances","op":"instance.list","args":{"view":"summary"}}
'@ | ad3-evolution --mode demo agent batchMecanismos que reduzem contexto e aumentam previsibilidade:
view: "summary"para coleções;- allowlist read-only, sem dispatch dinâmico;
- JSONL para lotes e loops externos;
capabilitiescompactas e determinísticas;- redação de telefone/segredo e sanitização de webhook;
- ausência de banner, QR ou Pix em capabilities, JSON legado e JSONL.
O scheduler fica fora da CLI e do batch. CRM e NocoDB podem compor essas leituras externamente.
Toda mutação continua em plan/apply: revise ID, hash e alvo, então confirme
com o mesmo ID. Planos usados, vencidos ou incertos não recebem retry cego.
Criação/configuração de grupos, participantes, admins, settings, mensagens,
onboarding e webhook seguem esse fluxo. @lid só é aceito em leituras de chat;
mutações exigem telefone válido.
Quando a conversa tiver apenas @lid, use o ID opaco de chat list:
ad3-evolution chat recipient --instance aula --chat-id ID_DA_CONVERSA
ad3-evolution message plan-text --instance aula --chat-id ID_DA_CONVERSA `
--content-file mensagem.txtA CLI associa nome e foto da conversa a exatamente um contato telefônico; se
faltar um dado ou houver ambiguidade, não cria o plano. A saída mascara o
telefone. Nunca use @lid diretamente como destinatário.
webhook get retorna estado, eventos, flags, origem e hash do destino, sem URL
integral, query, userinfo ou headers. O protocolo também oferece number.check,
group.participants e group.invite.resolve como gates de leitura.
Sem argumentos e com --help, a CLI mostra EVOLUTION AD3 DIGITAL e a frase
de que foi feita para economizar tokens de agentes de IA. donate --no-color
mostra QR Pix offline em ASCII. Essa saída humana não se mistura à superfície de
máquina.
py -3 -m unittest discover -s tests -v
py -3 scripts\verify.py
py -3 scripts\quick_validate.pyO código-fonte fica visível neste repositório público, sob licença proprietária AD3 Digital. Visualização e forks dentro do GitHub seguem os termos do serviço; não há concessão de uso comercial, redistribuição externa ou oferta como serviço sem autorização escrita. Leia LICENSE.md.