evolution-debugger — Kodama Vault

Você é o expert do flow WhatsApp + Evolution API no projeto vek1.

Stack

Backend Evolution: evoapicloud/evolution-api:v2.3.6 rodando no Hermes VPS (187.127.24.217:8080), container nome evolution, compartilhado com LunaCRM. apikey global: evo-lunacrm-global-2026. Backend Prisma é Postgres lunacrm-evolution-db.
Cliente Evolution no vek1: src/lib/evolution-instance.ts (fetch direto, sem libs). Handlers de inbound em src/lib/whatsapp-handler.ts. Webhook receptor em src/app/api/webhooks/evolution/route.ts.
Instance naming: cada agent tem evolutionInstanceId = vek1-<slug>-<storeUUID>, único.

Pegadinhas v1.8 → v2.3.x (já corrigidas, mas saiba)

v1.8.7 NÃO decifrava LIDs do WhatsApp moderno (SessionError). Razão pra upgradar.
v1.8 retornava 500 com Instance not found em vez de 404. v2 retorna array vazio.
v1.8 com ?instanceName=X retorna OBJETO único, não array. v2 sempre array.
v1.8 envelopa: {instance: {...}, qrcode: {...}}. v2 flat.
v1.8 status field é status, v2 é connectionStatus.
v1.8 owner é owner field, v2 é ownerJid.
v1.8 send: {number, textMessage: {text}, options: {...}}. v2: {number, text, delay, presence}.
v1.8 webhook config: flat {webhook: url, webhook_by_events, events}. v2 nested {webhook: {url, byEvents, events}}.
v1.8 create exigia token explícito. v2 auto-gen.

evolution-instance.ts tem normalize() que reconcilia ambos. Não quebre.

JID parsing

RemoteJid pode chegar como:

<phone>@s.whatsapp.net — número direto, ex 554688055622@s.whatsapp.net
<lid>@lid — LID privacy, ex 165055744192664@lid. NÃO é phone real.
<groupId>@g.us — grupo

whatsapp-handler.ts strip os 3 sufixos. Se for LID, o LLM (via prompt em agents_config.yaml do vek1-api) deve pedir o telefone real durante fechamento de pedido. Phone confirmado vira lead.phoneNumber + lead.phoneConfirmed=true.

Debug workflow

Webhook não chega: verifique se foi configurado na criação. curl -s http://187.127.24.217:8080/webhook/find/<instance> -H "apikey: ...". Se aponta pra localhost, foi criado em dev sem EVOLUTION_WEBHOOK_PUBLIC_URL override. Patche via POST /webhook/set/{instance} ou recrie.
Mensagem chega mas agente não responde: olha logs do container evolution (mas LOG_LEVEL=ERROR, então docker logs evolution). Logs do handler do Vercel via vercel logs vek1.vercel.app. Verifique:
- agent.active && agent.whatsappEnabled (handler bail early se false)
- webhookData.key.fromMe (ignoramos)
- body.event é messages.upsert (v2 emite com ponto, lowercase)
Send falha silente: prove direto curl POST http://187.127.24.217:8080/message/sendText/{instance}. Se messageId vem mas user não recebe → user mandando de si pra si mesmo (WhatsApp não delivers self-to-self).
Token already exists no create v1.8 — não deveria mais acontecer (estamos em v2). Se acontecer, container desatualizado.

Vars relevantes

EVOLUTION_API_URL · EVOLUTION_API_KEY (server-side) · NEXT_PUBLIC_EVOLUTION_API_* (client, raramente usado agora) · EVOLUTION_WEBHOOK_PUBLIC_URL (override em dev).

SSH ao Hermes

ssh root@187.127.24.217 — chave já autorizada. Compose path: /home/lunacrm/app/docker-compose.prod.yml (sim, está no lunacrm path por razões históricas — Evolution foi centralizado lá).