Atualizar o WAHA

A pesquisa (AD-002) é clara: biblioteca sempre atualizada é prática anti-ban, e o WAHA solta versões todo mês. Ao mesmo tempo, o payload varia por engine e por versão. Por isso a imagem é fixada por tag e cada troca passa por um roteiro.

Onde a tag moraCopy Anchor Link

A imagem é sempre devlikeapro/waha, com a tag vinda de WAHA_IMAGE_TAG:

Em produção a tag é de engine + versão (o comentário do compose dá o exemplo gows-2026.8.2) e nunca latest. O valor fica no ambiente do compose no Dokploy, junto com os outros segredos (AD-012). .env.example só traz o valor de dev (arm), e o comentário lembra que a variável é lida apenas pelo compose.

O que não se perde numa trocaCopy Anchor Link

• As sessões ficam no Postgres do WAHA (waha-db, volume wahadata), não no disco do container. Trocar a imagem não desvincula ninguém.
• WHATSAPP_RESTART_ALL_SESSIONS: "true" reabre todas as sessões do banco no boot.
• Enquanto o WAHA está fora, os webhooks não chegam; ao voltar, cada sessão manda session.status de novo e a máquina de estados aplica (ver WAHA fora do ar).

O que o nosso código assume do WAHACopy Anchor Link

O adapter diz ter sido conferido contra o WAHA 2026.8.2. Numa versão nova, estes são os pontos que quebram em silêncio:

Roteiro de atualizaçãoCopy Anchor Link

1. Leia as notas da versão nova do WAHA procurando mudanças na engine GOWS, nos endpoints e nos status da tabela acima.

2. Local: troque WAHA_IMAGE_TAG no .env e suba só o WAHA.

   Copy Text

   docker compose pull waha
   docker compose up -d waha
   docker compose ps waha        # healthy = /health respondeu com a X-Api-Key
   curl -fsS -H "X-Api-Key: <WAHA_API_KEY>" http://localhost:3001/health

3. Com bun run gateway e bun run workers de pé, repita o smoke que validou a integração: sessão → webhook → gateway → workers → desafio → QR por SSE → desvincular. bun run pair:qr -- <seat-uid> grava o QR do pareamento aberto.

4. Confira nos logs do gateway que não há waha webhook refused (assinatura) e, nos workers, que provider event failed; left pending não aparece.

5. Se possível, pareie um celular de teste e deixe a sincronização de histórico rodar: é onde as variáveis WAHA_GOWS_DEVICE_HISTORY_SYNC_* aparecem.

6. Homologação: troque WAHA_IMAGE_TAG no ambiente do compose no Dokploy e faça o redeploy. Acompanhe a saúde: contagem de pairingsDegraded no overview e a tela Conexões.

7. Anote a tag anterior para voltar se algo quebrar.

Não misturar com mudança de históricoCopy Anchor Link

WAHA_HISTORY_DAYS e WAHA_HISTORY_MESSAGES_PER_CHAT são lidos pelo container no momento do vínculo e valem para todas as sessões: mudar qualquer um significa parear todos os celulares de novo. Não aproveite uma atualização de imagem para mexer neles. Ver Anti-ban.

FontesCopy Anchor Link

• backend/docker-compose.yml, backend/docker-compose.prod.yml, backend/.env.example
• backend/src/domains/channels/adapters/waha-adapter.ts, backend/src/domains/channels/webhooks/waha-webhook.ts, backend/src/domains/ingest/channels/whatsapp/waha-ingest.ts
• backend/apps/gateway/main.ts, backend/apps/workers/consume-provider-events.ts, backend/package.json
• Lane doc k-pairing-api.md (tag fixada via WAHA_IMAGE_TAG)
• Vault: AD-002, AD-012 (deploy Dokploy), research/2026-09-11-whatsapp-nao-oficial, problems/2026-09-11-waha-dashboard-loop-basic-auth, _state (smoke com WAHA real, "em homologação"), specs/2026-10-18-redesign-blueprint