Este tutorial cobre o caminho do zero até a primeira mensagem enviada por API. Ele pressupõe que você já decidiu por qual caminho vai conectar, porque isso muda um passo importante. Se ainda não decidiu, leia primeiro a seção sobre via oficial e Baileys no guia da Evolution API, porque a escolha tem consequência para o seu número.
O que você precisa antes de começar
Quatro coisas, e três delas não são a Evolution:
- Um servidor acessível pela internet. Um VPS de entrada resolve. Dimensionamento em hospedagem.
- Docker instalado. É a via de instalação oficial do projeto.
- Um subdomínio apontado para o IP do servidor, com certificado válido. Sem isso o webhook não funciona de forma confiável.
- O número de WhatsApp que você vai conectar, ou as credenciais do WhatsApp Business Platform se for pela via oficial.
Se o item 3 parecer chato, é porque é. E é exatamente onde a maioria trava. Vale considerar uma instalação já provisionada, que resolve certificado e domínio no momento da criação.
Passo 1: subir a Evolution
A instalação roda em container. Você define duas coisas na subida que importam para o resto: a chave de API global, que autentica todas as chamadas, e o banco de dados.
Sobre o banco, vale a mesma recomendação que faço para o n8n: se você já sabe que vai passar de uso leve, aponte para PostgreSQL desde o início em vez de aceitar o padrão mais simples. Migrar depois com histórico acumulado é trabalho que não precisava existir.
Sobre a chave: gere algo longo e aleatório. Ela dá acesso total à sua instalação, incluindo enviar mensagem por qualquer instância conectada. Trate como senha de root.
Passo 2: confirmar que subiu
Antes de conectar número, confirme que a instalação responde e que a autenticação funciona. Chame o endpoint que lista instâncias, enviando a sua chave no header.
Resposta com JSON, mesmo que a lista esteja vazia, significa que está tudo certo. Se vier erro de autenticação, a chave enviada não é a que o container recebeu. Se não vier nada, o problema é rede: porta, proxy ou firewall.
Esse teste parece dispensável e não é. Ele separa “a Evolution não funciona” de “meu proxy está errado”, e essas duas coisas se confundem por horas quando você pula esta etapa.
Passo 3: criar a instância e conectar o número
Cada número é uma instância nomeada. Você cria a instância com um nome, e é esse nome que vai
em todas as chamadas seguintes daquele número. Use algo que você reconheça em três meses:
vendas-sp é melhor que instancia1.
Na via Baileys, a criação devolve um QR code. Você lê com o aplicativo do celular, no menu de dispositivos conectados, do mesmo jeito que conecta o WhatsApp Web. Em segundos a instância aparece como conectada.
Na API oficial, não há QR code. Você informa as credenciais da sua conta no WhatsApp Business Platform, e a instância passa a operar pelo canal do Meta.
Um aviso prático para quem usa Baileys: a sessão pode cair. Celular sem internet por muito tempo, WhatsApp desconectando o dispositivo, atualização do aplicativo. Monte alerta para instância desconectada, porque descobrir isso pelo cliente reclamando é o pior jeito.
Passo 4: enviar a primeira mensagem
Com a instância conectada, o envio é um POST para o endpoint de mensagem de texto, informando o nome da instância na rota, o número de destino e o texto no corpo, com a sua chave no header.
Duas coisas que fazem esse primeiro envio falhar, e que valem conferir antes de procurar problema onde não tem:
O formato do número. Precisa incluir código do país. Número brasileiro sem o 55 na frente não chega, e a mensagem de erro não é óbvia sobre isso.
A primeira conversa. Na via oficial do Meta, você não pode simplesmente iniciar conversa com qualquer número usando texto livre: existe a regra de janela de atendimento e de template aprovado para primeiro contato. Se o seu teste for enviar “oi” para um número que nunca falou com você, ele vai falhar por regra de negócio, não por erro técnico. Teste respondendo alguém que te mandou mensagem primeiro.
Passo 5: receber mensagem via webhook
Enviar é a metade fácil. Receber é onde a automação de verdade começa.
Você configura uma URL de webhook na instância, e a Evolution passa a fazer POST nela a cada evento: mensagem recebida, status de entrega, mudança de conexão. O seu sistema, ou o n8n, trata o evento e decide o que responder.
Três regras que evitam a maior parte dos problemas aqui:
- Responda 200 rápido. Processe depois, em fila se necessário. Webhook que demora vira reentrega e mensagem duplicada.
- Espere duplicata. Trate o mesmo evento chegando duas vezes sem gerar duas respostas ao cliente.
- Filtre o que você escreveu. A instância também emite evento para mensagem enviada por você. Sem filtrar, o seu bot responde a si mesmo, e isso vira laço.
Os erros que consomem a primeira tarde
Vale listar, porque são sempre os mesmos e cada um custa uma hora de quem está começando.
“Instância criada mas nunca conecta.” O QR code tem validade curta. Se você gerou, foi almoçar e voltou, ele expirou. Gere de novo e leia em seguida. Se conectar e cair em segundos, o número provavelmente já está conectado em outro lugar consumindo a mesma sessão.
“Envio retorna sucesso e a mensagem não chega.” Quase sempre é o número de destino sem código do país, ou com formatação que a API aceitou e o WhatsApp não resolveu. Teste com o seu próprio número, escrito com 55 na frente e sem nenhum caractere além de dígito.
“Funciona no meu computador e não no servidor.” É porta ou proxy. A Evolution está de pé, mas o seu proxy reverso não está encaminhando, ou o firewall está fechando. O teste do Passo 2, chamando o endpoint de instâncias de fora do servidor, separa esses dois mundos em trinta segundos.
“O webhook recebe às vezes.” Se o seu endpoint demora para responder, a entrega falha e vira reentrega. Responda 200 imediatamente e processe depois. Endpoint que faz consulta em banco e chamada a API antes de responder é a causa mais comum.
“O bot está respondendo a si mesmo.” Você não filtrou os eventos de mensagem enviada por você. A instância emite evento para tudo, inclusive o que ela mandou. Sem o filtro, cada resposta gera um novo evento e o laço não fecha sozinho.
“Sumiu tudo depois que reiniciei o container.” O volume de dados não estava persistido. A sessão e as configurações moram no banco e no volume; sem persistência, reiniciar zera a instalação e todos os números precisam reconectar.
Passo 6: fechar a porta antes de esquecer
O passo que ninguém coloca em tutorial e que devia ser o primeiro.
Sua instalação da Evolution controla números de WhatsApp da sua operação. Uma instância alcançável com a chave padrão, ou com o painel aberto, é acesso ao seu canal de atendimento na mão de quem achar o endereço.
Chave longa e única. Painel restrito por IP ou atrás de autenticação. Versão em dia. E jamais a chave no front-end ou em repositório público, porque a Evolution não distingue chamada legítima de chamada com a chave certa.
Onde ir depois
Para dimensionar o servidor e escolher entre a versão Node e a Go, veja hospedagem. Para a conta completa de custo, incluindo a tarifa do Meta, veja preços. Para o julgamento sobre a ferramenta servir ao seu caso, o review. Se a conclusão for que você quer isso pronto, sem servidor para cuidar, compare com as plataformas em alternativas.