Evolution API do zero: instalar, deixar no ar 24 horas e ligar o WhatsApp por QR Code

Para que serve no AFK

• Atendimento 24 horas no WhatsApp. O robô 24h do AFK, na sua Cloudflare, responde nesse número com as mesmas Respostas automáticas e o mesmo Atendente IA do WhatsApp oficial, do Direct e do Telegram.
• Você responde, a IA sai. O número continua no seu celular. Quando você responde por ele, o robô percebe e a IA fica calada naquele contato pelo tempo que você marcou em Atendente IA (12 horas, se não mudou).
• Lead no CRM. Quem a IA qualifica como quente ou morno, ou pede um humano, entra no CRM sozinho.
• Campanhas pelo mesmo número. Em Campanhas, as mensagens que você aprova saem por ele, devagar e com limite por dia.

O que o robô ignora: grupo, status e canal. Depois de uma reconexão, mensagem com mais de 30 minutos também é ignorada, para não responder conversa velha.

A comparação entre a API oficial e o QR Code está em WhatsApp: API oficial da Meta ou QR Code. O jeito mais fácil, sem servidor, é o WhatsApp direto do painel, mas ele só responde com o computador ligado e o painel aberto. Esta página é para quem quer o QR Code 24 horas.

Antes: grátis ou pago

O que é grátis em todos os casos:

• A Evolution. Código aberto, licença Apache 2.0 com duas condições extras: não tirar o logo dos componentes visuais dela e mostrar ao administrador que a Evolution está em uso. O AFK mostra esse aviso no cartão e em Ligar canais.
• O Docker Desktop, para empresa com menos de 250 funcionários e faturamento menor que US$ 10 milhões por ano.
• O túnel da Cloudflare (cloudflared) e o robô 24h na sua conta grátis da Cloudflare (Cloudflare do zero: conta, 2FA, token do robô 24 horas e o seu domínio).

O risco, sem esconder:

O que o AFK faz para reduzir o risco:

• O robô só responde quem escreveu. Ele nunca inicia conversa.
• Quem escreve SAIR não recebe mais resposta automática nem campanha.
• Nas Campanhas por esse número (em ferramentas/campanhas/canais.py): no máximo 40 mensagens por dia, uma por vez, com intervalo aleatório de 35 a 95 segundos, só de segunda a sábado, das 8h às 20h. Nada sai sem você aprovar na tela.
• O aviso na tela de Campanhas: use só com quem já é seu contato. Número novo ou lista fria é risco alto de bloqueio.

Parte 1: preparar o número e a conta da Cloudflare

1. Separe um chip secundário, com o WhatsApp (ou WhatsApp Business) num celular que fica com você.
2. O WhatsApp desconecta os dispositivos conectados se você não abrir o WhatsApp no celular a cada 14 dias. Abra o app pelo menos uma vez por semana.
3. Publique o robô 24h na sua Cloudflare, se ainda não publicou: siga Cloudflare do zero: conta, 2FA, token do robô 24 horas e o seu domínio. Sem ele, a Evolution conecta, mas ninguém responde.

Parte 2: subir a Evolution no seu computador (grátis)

Pule para a Parte 3 se for usar VPS, ou para a Parte 4 se contratou hospedagem pronta.

1. Instale o Docker Desktop. Nas configurações dele, ligue a opção de abrir junto com o computador.
2. Abra a pasta do AFK e entre em templates\evolution. Ali estão o docker-compose.yml e o LEIA.md.
3. Crie a chave. Abra o Git Bash (menu Iniciar, digite git bash) e rode duas vezes:

   openssl rand -hex 24

   A primeira linha que sair é a chave da Evolution. A segunda é a senha do banco dela. Guarde as duas num gerenciador de senhas.

4. Na pasta templates\evolution, crie um arquivo chamado .env com estas três linhas, trocando pelos seus valores:

   EVOLUTION_URL_PUBLICA=https://evo.minhaempresa.com.br
   EVOLUTION_API_KEY=cole-aqui-a-primeira-linha
   EVOLUTION_DB_SENHA=cole-aqui-a-segunda-linha

5. No Git Bash, entre na pasta e suba:

   cd ~/Desktop/afk/templates/evolution
   docker compose up -d

   Troque afk pelo nome da pasta do seu AFK. Na primeira vez, ele baixa a Evolution, o banco e o cache. Confira com docker compose ps: os três serviços têm que aparecer rodando.

6. Dê um endereço https:// com o túnel da Cloudflare. Instale o cloudflared pela página oficial e escolha um caminho:
   • Com domínio na Cloudflare (endereço fixo, recomendado):

     cloudflared tunnel login
     cloudflared tunnel create evo
     cloudflared tunnel route dns evo evo.minhaempresa.com.br
     cloudflared tunnel run --url http://localhost:8080 evo

     Para subir sozinho junto com o computador, instale como serviço: cloudflared service install.

   • Sem domínio (só para testar): cloudflared tunnel --url http://localhost:8080. Ele mostra um endereço https://...trycloudflare.com. Esse endereço muda toda vez que o túnel reinicia e não tem garantia de ficar no ar.
7. Deixe o computador sem suspender: nas opções de energia do Windows, coloque a suspensão em Nunca.

A porta 8080 fica só no seu computador (127.0.0.1). Quem fala com a internet é o túnel, com https://. Não abra a porta 8080 no roteador.

Parte 3: subir a Evolution numa VPS

1. Copie a pasta templates/evolution para a VPS. Se o AFK já está nela (Painel do AFK numa VPS, para usar fora de casa), a pasta já está em /opt/afk/templates/evolution.
2. Instale o Docker na VPS, se ainda não tem, pelo guia oficial do Docker para Ubuntu.
3. Crie o .env ao lado do docker-compose.yml, como no passo 4 da Parte 2. Gere a chave e a senha com openssl rand -hex 24.
4. Suba com docker compose up -d.
5. Ponha HTTPS na frente com o Caddy. No Caddyfile:

   evo.minhaempresa.com.br {
     reverse_proxy 127.0.0.1:8080
   }

   No DNS do domínio, crie um registro A com o nome evo apontando para o IP da VPS.

6. Abra https://evo.minhaempresa.com.br no navegador. Tem que abrir com cadeado e mostrar uma resposta em texto da Evolution, não uma página de erro.

Parte 4: colar no AFK, ler o QR Code e ligar ao robô

1. No painel do AFK, abra Conexões, clique no cartão WhatsApp — Evolution API, cole em Endereço do servidor (o https:// da Evolution), API key (a chave do .env) e Nome da instância (por exemplo atendimento) e clique em Salvar conexão. Este cartão não tem o botão Testar: a conferência acontece no passo 3.
2. Abra Respostas automáticas → Ligar canais e desça até o cartão WhatsApp por QR code com servidor (Evolution).
3. Clique em Mostrar QR code. Se a instância ainda não existe, o AFK cria.
4. No celular do número secundário, abra o WhatsApp:
   • Android: toque nos três pontos → Dispositivos conectados → Conectar dispositivo.
   • iPhone: em Configurações, toque em Dispositivos conectados → Conectar dispositivo.

     Confirme com a digital ou o PIN e escaneie o QR Code da tela do AFK.

5. Com o número conectado, clique em Ligar ao robô 24h. O AFK atualiza o robô e aponta a Evolution para ele.
6. De outro número, mande "oi" para o número secundário. A resposta tem que chegar.
7. Para a IA responder o que as regras não cobrem: em Respostas automáticas → Atendente IA, marque WhatsApp em Onde ele atende e clique em Publicar no robô 24h.

Atalho: em Ligar canais existe o botão Salvar e Mostrar QR Code, que confere a chave na hora e grava a Evolution. Se as Campanhas já usam outro WhatsApp (o oficial ou a Z-API), o atalho não troca: para as Campanhas saírem pela Evolution, salve o cartão em Conexões.

Onde a chave fica. No .env da pasta do AFK e no robô 24h, que precisa dela para responder. Ela não aparece na conversa. Quem tem o endereço e a chave controla o seu WhatsApp. Nunca cole em chat, print ou WhatsApp.

No dia a dia

Se a chave vazar: troque EVOLUTION_API_KEY no .env da Evolution, rode docker compose up -d, cole a nova no AFK e clique em Ligar ao robô 24h. No celular, confira Dispositivos conectados e remova o que você não reconhece.

Erros e soluções

Se nada funcionar

Veja Travou ou quero sugerir uma melhoria: o que mandar. Mande o texto do erro e a saída de docker compose logs evolution --tail 30. Nunca mande a chave nem o .env.

Fontes oficiais (conferido em 30/10/2026): docs.evolutionfoundation.com.br/evolution-api/install/docker (instalação com Docker; porta 8080; AUTHENTICATION_API_KEY; PostgreSQL e Redis como pré-requisitos) · docs.evolutionfoundation.com.br/evolution-api/connect-instance (/instance/connect; cabeçalho apikey; QR em base64; erros 401 e 404) · github.com/EvolutionAPI/evolution-api/releases (v2.3.7 é a última estável; 2.4.0-rc é pré-lançamento, não para produção) · github.com/EvolutionAPI/evolution-api/blob/main/LICENSE (Apache 2.0 com condições de logo e de aviso de uso) · docs.docker.com/subscription/desktop-license (Docker Desktop grátis para empresa com menos de 250 funcionários e menos de US$ 10 milhões por ano) · developers.cloudflare.com/.../trycloudflare (túnel rápido sem conta; endereço muda a cada criação; só para teste, sem garantia de ficar no ar) · faq.whatsapp.com/1317564962315842 (Dispositivos conectados → Conectar dispositivo; até 4 dispositivos; abrir o celular principal a cada 14 dias) · whatsapp.com/legal/terms-of-service (proíbe mensagem automática e em massa e acesso automatizado; suspensão ou desativação da conta).