--- title: "Hospedar a Evolution API (WhatsApp) em uma VPS com Docker" description: "Suba a Evolution API com Docker Compose, PostgreSQL e Redis, conecte o WhatsApp pelo QR Code, ponha Nginx com HTTPS na frente e integre com o n8n." url: "https://streethosting.com.br/guias/vps/hospedar-evolution-api-whatsapp-vps" category: "vps" slug: "hospedar-evolution-api-whatsapp-vps" datePublished: "2026-11-13" dateModified: "2026-11-13" author: "Equipe StreetHosting" difficulty: "avancado" language: "pt-BR" keywords: - "evolution api whatsapp vps" - "instalar evolution api docker" - "api whatsapp não oficial" - "evolution api n8n" - "evolution api qr code" - "evolution api nginx https" --- # Evolution API na VPS: WhatsApp com Docker Compose, PostgreSQL e Redis A Evolution API é uma API de WhatsApp de código aberto, muito usada com n8n e Chatwoot. Veja como subir com Docker Compose, parear pelo QR Code, publicar com HTTPS e quais são os riscos de uma conexão que não é oficial. > **Resposta rápida** > > A **Evolution API** é uma API de WhatsApp de código aberto: você conecta um número pelo QR Code e passa a enviar e receber mensagens por HTTP, o que combina bem com n8n e Chatwoot. Na VPS ela roda com Docker Compose junto de PostgreSQL e Redis, protegida por uma chave global de API e publicada com Nginx e HTTPS. Antes de começar, saiba que é uma conexão **não oficial**: o número pode ser banido. Use um número dedicado e evite disparo em massa. A via oficial é a API do WhatsApp Business da Meta. ## O que é a Evolution API e o risco real A Evolution API é um servidor que fica entre o seu sistema e o WhatsApp. Ela mantém uma sessão do WhatsApp Web conectada ao seu número e expõe uma API REST: você chama um endereço para mandar uma mensagem de texto, imagem ou áudio, e configura um webhook para ser avisado de cada mensagem que chega. Por isso aparece tanto em automações de atendimento, com n8n para a lógica e Chatwoot para a caixa de entrada. > **Atenção** > > Esta é uma conexão não oficial com o WhatsApp. A Meta não autoriza esse tipo de uso e pode banir o número, às vezes sem aviso. Nunca use o seu número pessoal ou o principal da empresa. Registre um número dedicado ao projeto, não faça disparo em massa, não envie mensagens para quem nunca falou com você e mantenha um ritmo parecido com o de uma pessoa. Se o seu negócio depende do WhatsApp e não pode correr esse risco, a alternativa oficial é a API do WhatsApp Business da Meta (Cloud API). Ela exige conta comercial verificada, mensagens iniciadas pela empresa por meio de templates aprovados e cobra por essas mensagens. Dá mais trabalho para começar e é o caminho que a Meta apoia. Resolvido esse ponto, o restante do guia é técnico: como deixar a Evolution API rodando de forma estável na sua VPS. ## Preparar a VPS Você precisa de uma VPS com Ubuntu, Docker e o plugin do Compose, um domínio ou subdomínio apontado para o IP da VPS (por exemplo `api.seudominio.com.br`) e o Nginx instalado para o HTTPS. Se ainda não tem o Docker, siga o [guia de instalação do Docker no Ubuntu](https://streethosting.com.br/guias/vps/instalar-docker-ubuntu-vps). Para entender os arquivos que vem a seguir, o [guia de Docker Compose](https://streethosting.com.br/guias/vps/docker-compose-vps-guia) explica a estrutura. Sobre tamanho: para uma ou duas instâncias, 2 GB de RAM funcionam, mas com pouca folga, já que a API, o PostgreSQL e o Redis dividem a memória. Prefira 4 GB se pretende crescer. ``` mkdir -p ~/evolution && cd ~/evolution openssl rand -hex 24 # gera uma chave aleatória para AUTHENTICATION_API_KEY openssl rand -hex 16 # gera outra para a senha do PostgreSQL ``` ## Docker Compose com PostgreSQL e Redis > **Atenção** > > O nome da imagem, a tag e as variáveis da Evolution API mudam entre versões. O arquivo abaixo é um ponto de partida mínimo baseado na documentação oficial (doc.evolution-api.com e o repositório EvolutionAPI/evolution-api no GitHub) para a linha 2.x. A tag v2.3.7 era a versão estável mais nova no Docker Hub (evoapicloud/evolution-api) em novembro de 2026. Antes de subir, confira se saiu outra e leia o arquivo `.env.example` da versão que você escolher. Não use a tag latest em produção: fixe a versão. Crie o arquivo `docker-compose.yml`: ``` services: evolution-api: container_name: evolution_api image: evoapicloud/evolution-api:v2.3.7 restart: always depends_on: - postgres - redis ports: - "127.0.0.1:8080:8080" env_file: - .env volumes: - evolution_instances:/evolution/instances postgres: image: postgres:15 container_name: evolution_postgres restart: always environment: POSTGRES_DB: evolution_db POSTGRES_USER: evolution POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - postgres_data:/var/lib/postgresql/data redis: image: redis:7 container_name: evolution_redis restart: always command: redis-server --appendonly yes volumes: - evolution_redis:/data volumes: evolution_instances: postgres_data: evolution_redis: ``` A porta 8080 fica presa em 127.0.0.1: a API não é alcançável direto da internet, só pelo Nginx que vamos configurar. O PostgreSQL e o Redis nem publicam porta, só a API conversa com eles pela rede interna do Compose. ## As variáveis principais No mesmo diretório, crie o `.env`. Este é o conjunto mínimo para a versão 2: ``` SERVER_URL=https://api.seudominio.com.br SERVER_PORT=8080 AUTHENTICATION_API_KEY=COLE_A_PRIMEIRA_CHAVE_AQUI POSTGRES_PASSWORD=COLE_A_SEGUNDA_CHAVE_AQUI DATABASE_PROVIDER=postgresql DATABASE_CONNECTION_URI=postgresql://evolution:COLE_A_SEGUNDA_CHAVE_AQUI@postgres:5432/evolution_db?schema=evolution_api DATABASE_SAVE_DATA_INSTANCE=true DATABASE_SAVE_DATA_NEW_MESSAGE=true DATABASE_SAVE_DATA_CONTACTS=true DATABASE_SAVE_DATA_CHATS=true CACHE_REDIS_ENABLED=true CACHE_REDIS_URI=redis://redis:6379/6 CACHE_REDIS_PREFIX_KEY=evolution CACHE_REDIS_SAVE_INSTANCES=false CACHE_LOCAL_ENABLED=false ``` - **AUTHENTICATION_API_KEY:** a chave global. Quem tem ela controla todas as instâncias, então trate como senha, use um valor longo e aleatório e nunca a coloque no código de um site. - **SERVER_URL:** o endereço público da API, com https. É usado para montar links que a própria API devolve, então ponha o domínio final. - **DATABASE_PROVIDER e DATABASE_CONNECTION_URI:** dizem que o banco é PostgreSQL e como chegar nele. O host é o nome do serviço do Compose (postgres), nunca localhost, porque cada contêiner tem o seu próprio localhost. - **CACHE_REDIS_*:** ligam o cache no Redis. O host também é o nome do serviço (redis). Proteja o arquivo e suba tudo: ``` chmod 600 .env docker compose up -d docker compose logs -f evolution-api ``` Nos logs, espere a API informar que está ouvindo na porta 8080 e que conectou ao banco. Na primeira subida a imagem prepara as tabelas no PostgreSQL, então pode demorar um pouco. Se aparecer erro de conexão com o banco, confira a senha na URI e se o PostgreSQL já terminou de iniciar. ## Criar a instância e ler o QR Code Cada número de WhatsApp é uma **instância**. Você cria uma chamando a API com a chave global no cabeçalho `apikey`. Por enquanto a API só responde dentro da VPS, então rode na própria máquina: ``` curl -X POST http://127.0.0.1:8080/instance/create \ -H "apikey: SUA_CHAVE_GLOBAL" \ -H "Content-Type: application/json" \ -d '{"instanceName": "atendimento", "integration": "WHATSAPP-BAILEYS", "qrcode": true}' ``` A resposta traz o QR Code (em base64) e a instância fica aguardando a leitura. Se quiser pedir o QR Code de novo, chame `GET /instance/connect/atendimento` com o mesmo cabeçalho. Como ler uma imagem em base64 no terminal é ruim, o jeito mais prático é o painel web, o Evolution Manager, que mostra o QR Code como imagem. No docker-compose.yaml do repositório oficial ele aparece como um serviço separado; veja na documentação da sua versão como publicar e não o deixe aberto para a internet sem proteção. 1. No celular com o número dedicado, abra o WhatsApp e vá em Aparelhos conectados (em alguns celulares aparece como Dispositivos conectados). 2. Toque em Conectar um aparelho. 3. Escaneie o QR Code da instância antes que ele expire. O código troca em poucos segundos e a API limita as tentativas. 4. Confirme o estado da conexão com `GET /instance/connectionState/atendimento`: o valor esperado é open. Para testar o envio, uma mensagem de texto fica assim. O número vai com código do país e DDD, sem espaço nem símbolo: ``` curl -X POST http://127.0.0.1:8080/message/sendText/atendimento \ -H "apikey: SUA_CHAVE_GLOBAL" \ -H "Content-Type: application/json" \ -d '{"number": "5511999999999", "text": "Teste da Evolution API"}' ``` Os caminhos e os campos acima seguem a documentação da linha 2.x, mas podem mudar de versão para versão. Em caso de erro 404 ou de campo rejeitado, compare com a referência da API na documentação oficial. ## Nginx com HTTPS na frente Para o n8n, o Chatwoot ou um site chamarem a API de fora, publique a porta 8080 pelo Nginx com HTTPS. O passo a passo do proxy está no [guia de proxy reverso com Nginx](https://streethosting.com.br/guias/vps/configurar-nginx-reverse-proxy-vps) e o do certificado no [guia de SSL com Let's Encrypt](https://streethosting.com.br/guias/vps/certificado-ssl-vps-lets-encrypt-nginx). O bloco do site fica assim: ``` server { server_name api.seudominio.com.br; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 120s; client_max_body_size 50m; } } ``` Os cabeçalhos Upgrade e Connection permitem WebSocket, e o `client_max_body_size` deixa passar o envio de imagens e arquivos. Depois de ativar o site e emitir o certificado, teste de fora com `curl -H "apikey: SUA_CHAVE_GLOBAL" https://api.seudominio.com.br/instance/fetchInstances`. Sem a chave, a API recusa a chamada. > **Dica** > > Como a chave global dá controle total, considere liberar o acesso à API só para os IPs que precisam dela, com o [firewall UFW](https://streethosting.com.br/guias/vps/firewall-ufw-vps-ubuntu) ou com regras de allow no Nginx. E guarde a chave num gerenciador de senhas. ## Integrar com o n8n O n8n entra nos dois sentidos. Para **receber** mensagens, crie um fluxo que começa em um nó Webhook (método POST), copie a URL de produção dele e cadastre essa URL como webhook da instância, com o evento de mensagem recebida ligado. A Evolution API passa a mandar um POST ao n8n a cada mensagem, com o número, o texto e os dados do contato. Os campos de webhook mudaram entre versões, então configure pelo Evolution Manager ou siga a referência da sua versão. Para **enviar**, use um nó HTTP Request com método POST para `/message/sendText/NOME_DA_INSTANCIA`, o cabeçalho apikey e um corpo JSON com number e text, os mesmos campos do teste feito antes. Guarde a chave numa credencial do n8n em vez de deixar escrita no fluxo. Se o n8n estiver na mesma VPS, ponha os dois na mesma rede do Docker e chame a API pelo nome do serviço (por exemplo `http://evolution-api:8080`) em vez de passar pela internet. A instalação do n8n está no [guia de n8n na VPS](https://streethosting.com.br/guias/vps/hospedar-n8n-vps-brasil). > **Atenção** > > Automatizar respostas é diferente de disparar para uma lista. Fluxos que respondem a quem escreveu primeiro, em ritmo moderado, são bem menos arriscados do que campanhas para contatos frios. Coloque um intervalo entre mensagens e um limite diário no seu fluxo. ## Onde rodar isso na StreetHosting A Evolution API roda como contêiner e precisa de Docker e de um Nginx com certificado, então o que serve é uma VPS com acesso root. Nas VPS da StreetHosting a virtualização é KVM, com IPv4 dedicado, AntiDDoS incluso e servidor em São Paulo, com ativação automática em cerca de 60 segundos depois do pagamento por Pix ou cartão. Para a API com PostgreSQL e Redis e o n8n na mesma máquina, a VPS Xeon com 2 vCPU e 2 GB de RAM, a partir de R$ 26,00 por mês, serve para começar com uma instância. Se pretende várias instâncias, histórico grande de mensagens ou outras aplicações juntas, suba para uma [VPS Ryzen](https://streethosting.com.br/vps/ryzen) com mais memória. ## Perguntas frequentes ### A Evolution API é oficial do WhatsApp? Não. A Evolution API se conecta ao WhatsApp Web, imitando o aplicativo, e isso não é um canal autorizado pela Meta. A Meta pode bloquear o número a qualquer momento. A alternativa oficial é a API do WhatsApp Business da Meta, que exige conta comercial e templates aprovados, e cobra pelas mensagens de template que a empresa envia. ### O meu número pode ser banido usando a Evolution API? Pode. O risco aumenta com disparo em massa, envio para quem não conhece o número, muitas mensagens iguais e números recém criados. Use um número dedicado ao projeto, responda a quem escreveu primeiro, mantenha um ritmo humano e não use a ferramenta para spam. ### Quanta memória a Evolution API precisa? Para poucas instâncias, uma VPS de 2 GB roda a API, o PostgreSQL e o Redis juntos, com pouca folga. Cada instância conectada consome memória, e o histórico de mensagens no banco cresce com o tempo. Para várias instâncias, prefira 4 GB ou mais e monitore o consumo. ### Preciso de PostgreSQL e Redis para rodar? A versão 2 usa um banco relacional (PostgreSQL ou MySQL) para guardar instâncias e mensagens, e o Redis serve de cache. A documentação oficial descreve o PostgreSQL como o caminho recomendado. Confira na documentação da versão que você instalar, porque as variáveis mudam entre versões. ### Como o n8n conversa com a Evolution API? De duas formas. Para receber mensagens, você aponta o webhook da instância para um nó Webhook do n8n. Para enviar, o n8n usa o nó HTTP Request chamando a API da Evolution com a chave no cabeçalho apikey. Se os dois estiverem na mesma VPS e na mesma rede do Docker, use o nome do serviço em vez do endereço público. ## Guias relacionados - [Hospedar n8n em VPS no Brasil: automação com baixa latência e boas práticas](https://streethosting.com.br/guias/vps/hospedar-n8n-vps-brasil.md) - [Como instalar Docker no Ubuntu 22.04 ou 24.04 em VPS (guia direto ao ponto)](https://streethosting.com.br/guias/vps/instalar-docker-ubuntu-vps.md) - [Como configurar o Nginx como reverse proxy na VPS](https://streethosting.com.br/guias/vps/configurar-nginx-reverse-proxy-vps.md) - [Certificado SSL na VPS com Let's Encrypt e Nginx](https://streethosting.com.br/guias/vps/certificado-ssl-vps-lets-encrypt-nginx.md) - [Docker Compose na VPS: aplicação e banco de dados em um compose.yaml](https://streethosting.com.br/guias/vps/docker-compose-vps-guia.md) ## Produtos citados - https://streethosting.com.br/vps ## Dados estruturados ```json [ { "@context": "https://schema.org", "@type": [ "Article", "TechArticle" ], "headline": "Evolution API na VPS: WhatsApp com Docker Compose, PostgreSQL e Redis", "name": "Hospedar a Evolution API (WhatsApp) em uma VPS com Docker", "abstract": "A Evolution API é uma API de WhatsApp de código aberto, muito usada com n8n e Chatwoot. Veja como subir com Docker Compose, parear pelo QR Code, publicar com HTTPS e quais são os riscos de uma conexão que não é oficial.", "description": "Suba a Evolution API com Docker Compose, PostgreSQL e Redis, conecte o WhatsApp pelo QR Code, ponha Nginx com HTTPS na frente e integre com o n8n.", "datePublished": "2026-11-13", "dateModified": "2026-11-13", "author": { "@type": "Organization", "name": "Equipe StreetHosting" }, "publisher": { "@type": "Organization", "name": "StreetHosting", "url": "https://streethosting.com.br" }, "inLanguage": "pt-BR", "mainEntityOfPage": { "@type": "WebPage", "@id": "https://streethosting.com.br/guias/vps/hospedar-evolution-api-whatsapp-vps" } }, { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "A Evolution API é oficial do WhatsApp?", "acceptedAnswer": { "@type": "Answer", "text": "Não. A Evolution API se conecta ao WhatsApp Web, imitando o aplicativo, e isso não é um canal autorizado pela Meta. A Meta pode bloquear o número a qualquer momento. A alternativa oficial é a API do WhatsApp Business da Meta, que exige conta comercial e templates aprovados, e cobra pelas mensagens de template que a empresa envia." } }, { "@type": "Question", "name": "O meu número pode ser banido usando a Evolution API?", "acceptedAnswer": { "@type": "Answer", "text": "Pode. O risco aumenta com disparo em massa, envio para quem não conhece o número, muitas mensagens iguais e números recém criados. Use um número dedicado ao projeto, responda a quem escreveu primeiro, mantenha um ritmo humano e não use a ferramenta para spam." } }, { "@type": "Question", "name": "Quanta memória a Evolution API precisa?", "acceptedAnswer": { "@type": "Answer", "text": "Para poucas instâncias, uma VPS de 2 GB roda a API, o PostgreSQL e o Redis juntos, com pouca folga. Cada instância conectada consome memória, e o histórico de mensagens no banco cresce com o tempo. Para várias instâncias, prefira 4 GB ou mais e monitore o consumo." } }, { "@type": "Question", "name": "Preciso de PostgreSQL e Redis para rodar?", "acceptedAnswer": { "@type": "Answer", "text": "A versão 2 usa um banco relacional (PostgreSQL ou MySQL) para guardar instâncias e mensagens, e o Redis serve de cache. A documentação oficial descreve o PostgreSQL como o caminho recomendado. Confira na documentação da versão que você instalar, porque as variáveis mudam entre versões." } }, { "@type": "Question", "name": "Como o n8n conversa com a Evolution API?", "acceptedAnswer": { "@type": "Answer", "text": "De duas formas. Para receber mensagens, você aponta o webhook da instância para um nó Webhook do n8n. Para enviar, o n8n usa o nó HTTP Request chamando a API da Evolution com a chave no cabeçalho apikey. Se os dois estiverem na mesma VPS e na mesma rede do Docker, use o nome do serviço em vez do endereço público." } } ] } ] ```