Evolution API na VPS: primeiro acesso e como conectar o WhatsApp

A Evolution API é um projeto de código aberto que conecta o WhatsApp aos seus sistemas: com ela, um site, um CRM ou uma automação consegue enviar e receber mensagens de WhatsApp por uma API. Ela já vem instalada na sua VPS, com banco de dados próprio, HTTPS e um painel de gerenciamento.

O que vale para todos os aplicativos (SSH, log, reiniciar) está no artigo Sua VPS com aplicativo: dados de acesso, onde fica cada coisa, ver o log, reiniciar o app.

O que vem no e-mail

Nos endereços, SEU-IP é o IP da VPS com traços no lugar dos pontos. A Evolution API não tem usuário e senha: quem tem a API key controla tudo, então guarde essa chave como se fosse uma senha.

Primeiro acesso ao painel

1. Abra o painel: https://evo.SEU-IP.yhostbr.online/manager.
2. A tela de entrada aparece em inglês. O campo Server URL já vem preenchido com o endereço da sua Evolution (https://evo.SEU-IP.yhostbr.online): deixe como está.
3. Em API Key Global, cole a API key que veio no e-mail.
4. Clique em Login.

Depois de entrar, use o seletor de idioma no topo do painel para escolher português. A escolha fica salva no navegador. A partir daqui, os nomes estão como aparecem no painel em português.

Conectar o WhatsApp

Cada número de WhatsApp conectado é uma instância.

1. Na tela Instâncias, clique no botão Instância (com o sinal de +).
2. Em Nome, dê um nome para a conexão. Use um nome simples, sem espaços nem acentos (por exemplo, loja), porque ele vai no endereço das chamadas da API.
3. Em Canal, deixe Baileys, que é a conexão pelo QR code. O campo Token já vem preenchido e o campo Número é opcional.
4. Clique em Salvar. Aparece "Instância criada com sucesso".
5. Clique no nome da instância, no topo do cartão dela, para abrir.
6. Clique em Gerar QR Code. O QR code aparece na tela.

No celular com o número que vai ser usado, abra o WhatsApp. No Android, toque no ícone ⋮ (três pontinhos) e depois em Dispositivos conectados e Conectar dispositivo. No iPhone, toque em Configurações (ou na sua foto do perfil) e depois em Dispositivos conectados e Conectar dispositivo. Aponte a câmera para o QR code.

Quando o celular terminar de conectar, a instância passa a aparecer como Conectado no painel.

Usar a API

Toda chamada à API leva a chave no cabeçalho apikey. Exemplo de envio de uma mensagem de texto pelo terminal (troque o nome da instância, a chave e o número):

curl -X POST "https://evo.SEU-IP.yhostbr.online/message/sendText/NOME-DA-INSTANCIA" \
  -H "apikey: SUA-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "5511999999999", "text": "Olá! Mensagem de teste."}'

O número vai só com dígitos, começando com 55 (Brasil) e o DDD. Esse comando funciona no terminal do Linux ou do Mac, e também pelo SSH na própria VPS.

Cada instância tem também o seu próprio Token (o que aparece na criação). Ele funciona no lugar da API key, mas só para aquela instância. Use o token quando quiser dar a um sistema acesso a um número só.

A documentação oficial da API está em https://docs.evolutionfoundation.com.br/evolution-api.

Receber as mensagens no seu sistema (webhook)

Para o seu sistema ser avisado quando chega uma mensagem, configure um webhook:

1. No painel, abra a instância e vá em Eventos > Webhook.
2. Ligue Ativo e, em URL, coloque o endereço do seu sistema que vai receber os avisos.
3. Em Eventos, marque os avisos que você quer receber. Para mensagens novas, marque MESSAGES_UPSERT. Para saber quando a conexão cai ou volta, marque CONNECTION_UPDATE.
4. Clique em Salvar. Aparece "Webhook aplicado com sucesso".

A Evolution envia cada aviso por POST, com os dados em JSON, para o endereço que você colocou.

Trocar a API key

A API key faz o papel da senha. Para trocar, entre na VPS pelo SSH e rode:

cd /opt/yhost/evolution
sed -i "s/^EVO_KEY=.*/EVO_KEY=$(openssl rand -hex 20)/" .env
docker compose up -d
grep EVO_KEY .env

O último comando mostra a chave nova (o que vem depois de EVO_KEY=). Depois disso, a chave antiga para de funcionar: entre de novo no painel com a nova e troque a chave em todos os sistemas que usam a sua API.

Cuidados com o WhatsApp

• A Evolution API conecta o WhatsApp do mesmo jeito que o WhatsApp Web, como um dispositivo conectado ao seu celular. Não é a API oficial do WhatsApp para empresas.
• Evite mensagens em massa e mensagens para quem não pediu. O WhatsApp pode bloquear números que fazem isso.
• Abra o WhatsApp no celular principal pelo menos uma vez a cada 14 dias. É uma regra do WhatsApp: se o celular principal ficar mais tempo sem usar o app, os dispositivos conectados são desconectados.

Onde roda na VPS

Problemas comuns

A página não abre logo depois da criação

A instalação leva de 2 a 6 minutos depois que a VPS liga. Espere uns 10 minutos e tente de novo numa janela anônima. Para acompanhar, veja o log da instalação pelo SSH: tail -n 30 /var/log/yhost-app.log.

O navegador avisa que a conexão não é segura

O certificado HTTPS ainda não saiu. Ele costuma sair poucos minutos depois da instalação e, se o endereço da VPS demorou a ficar pronto, o sistema tenta de novo sozinho a cada 10 minutos. Espere e recarregue a página. Enquanto o aviso aparecer, não digite sua chave. Se o aviso continuar depois de 1 hora, abra um chamado.

A API responde 401 (Unauthorized)

A chave enviada no cabeçalho apikey está errada ou foi trocada. Confira a chave em /opt/yhost/evolution/.env, na linha EVO_KEY.

O QR code venceu

Cada QR code vale menos de um minuto, e a janela do painel não troca o código sozinha. Feche a janela, clique de novo em Gerar QR Code e leia logo em seguida.

O WhatsApp desconectou

Confira se o celular principal está com internet e se o WhatsApp foi aberto nele nos últimos 14 dias. Depois conecte de novo pelo painel, lendo um QR code novo.

Precisa de ajuda?

Abra um chamado em https://yhost.com.br/painel/suporte. Informe o IP da VPS e o que aconteceu. Se tiver uma mensagem de erro, mande um print.