Faça deploy da Evolution API (API do WhatsApp)

Introdução

Para desenvolver e hospedar a Evolution API na Square Cloud, siga a sequência de configurações e pré-requisitos abaixo. Este guia cobre todo o processo, da configuração inicial ao deploy em produção.

Pré-requisitos

Conta Square Cloud: Cadastre-se através da página de cadastro usando seu e-mail.
Plano ativo: Garante recursos dedicados e desempenho otimizado para seu aplicativo. Confira nossos planos disponíveis e escolha o mais adequado às suas necessidades.

A Evolution API é uma API open source para WhatsApp. Ela gerencia várias instâncias do WhatsApp em um só lugar, pelo gerenciador web ou pela API REST, e as conecta a ferramentas como n8n, Chatwoot e Typebot. Este guia usa o runtime Node.js.

Obtenha o projeto

Baixe o projeto das nossas releases do evolutionapi-web, que já têm os arquivos necessários para fazer o deploy na Square Cloud, ou do repositório oficial.

O repositório oficial lista o typescript em devDependencies. A Square Cloud instala as dependências em modo de produção, sem as devDependencies, então a etapa npm run build falha. A nossa release já o move para dependencies; com o repositório oficial, mova-o você mesmo.

Configure a Evolution API

A Evolution API lê um arquivo .env na raiz do projeto quando inicia, então esse arquivo vai no seu ZIP. Comece pelo .env da nossa release (ou pelo .env.example do repositório oficial) e edite as variáveis abaixo. As variáveis definidas em Variáveis de ambiente no dashboard têm prioridade sobre o arquivo .env, o que torna o dashboard o melhor lugar para segredos como AUTHENTICATION_API_KEY e DATABASE_CONNECTION_URI. Veja Variáveis de ambiente.

Banco de dados

A Evolution API precisa de um banco de dados PostgreSQL. Você pode hospedar um na Square Cloud com o plano Standard ou superior: veja como criar e conectar um banco de dados gerenciado. Após criá-lo, defina a URL dele no .env como DATABASE_CONNECTION_URI, junto com o certificado de cliente para a conexão com o PostgreSQL. Veja um exemplo da configuração necessária:

.env

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://squarecloud:password@host:port/database?sslmode=require&sslidentity=path/to/client-identity.p12&sslpassword=p12password'
DATABASE_CONNECTION_CLIENT_NAME='evolution_exchange'
DATABASE_SAVE_DATA_INSTANCE=true
DATABASE_SAVE_DATA_NEW_MESSAGE=true
DATABASE_SAVE_MESSAGE_UPDATE=true
DATABASE_SAVE_DATA_CONTACTS=true
DATABASE_SAVE_DATA_CHATS=true
DATABASE_SAVE_DATA_LABELS=true
DATABASE_SAVE_DATA_HISTORIC=true
DATABASE_SAVE_IS_ON_WHATSAPP=true
DATABASE_SAVE_IS_ON_WHATSAPP_DAYS=7
DATABASE_DELETE_MESSAGE=true

A Evolution API se conecta pelo Prisma, que espera o certificado de cliente como um arquivo .p12. Baixe os arquivos do certificado (.crt e .key) na página do banco de dados no dashboard, converta-os e coloque o .p12 no seu projeto:

openssl pkcs12 -export -out client-identity.p12 -inkey <certificate>.key -in <certificate>.crt

A senha de exportação que você escolher é o sslpassword da URL, e o sslidentity é o caminho do arquivo .p12. Mantenha o .p12 no seu ZIP, já que a aplicação o lê do disco.

Aplique as migrações

Com a variável de ambiente e o certificado configurados, aplique as migrações no seu banco de dados. Na pasta do projeto, no seu computador, instale as dependências com npm install (é preciso ter o arquivo runWithProvider.js) e execute o seguinte comando:

Windows
Linux

npm run db:deploy:win

npm run db:deploy

Vai atualizar de uma versão anterior? Rode o mesmo comando de novo antes de enviar os arquivos novos, porque versões novas podem trazer migrações novas.

Servidor

Conforme mostrado no arquivo .env.example do repositório, defina as variáveis do servidor: SERVER_TYPE, SERVER_PORT, SERVER_URL e o idioma.

.env

SERVER_NAME=evolution
SERVER_TYPE=http
SERVER_PORT=80
# A URL da sua aplicação: https://<subdomain>.squareweb.app, ou o seu domínio personalizado
SERVER_URL="https://my-evolution-api.squareweb.app"
LANGUAGE="pt-BR"
# Outras variáveis abaixo...

A Evolution API lê a porta do SERVER_PORT (e não da PORT) e, sem ele, usa 8080, então mantenha SERVER_PORT=80.

Chave de API global

É importante configurar uma chave de API global segura para evitar acessos não autorizados. Substitua-a por um valor aleatório e longo, só seu: a chave dos arquivos de exemplo é pública.

.env

# Outras variáveis...
AUTHENTICATION_API_KEY=MySuperSecureAPIKEY

Cache Redis (opcional)

Você pode configurar um sistema de cache na Evolution API. Para isso, você precisará de um banco de dados Redis, que também pode ser hospedado na Square Cloud.
Para configurá-lo, você também precisará baixar o certificado e definir a URL de conexão. Repare no esquema rediss://: os bancos de dados da Square Cloud só aceitam conexões TLS.

.env

CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI="rediss://default:MySecurePassword@square-cloud-db-ID.squareweb.app:7170"
CACHE_REDIS_TTL=604800
# Prefixo serve para diferenciar dados de uma instalação para outra que estejam usando o mesmo Redis
CACHE_REDIS_PREFIX_KEY=evolution
# Habilitar esta variável fará com que as informações de conexão sejam salvas no Redis e não no banco de dados.
CACHE_REDIS_SAVE_INSTANCES=false

Configure a Square Cloud

Crie um arquivo squarecloud.app na raiz do projeto. O comando START gera o client do Prisma, faz o build do projeto e o inicia; a instalação e o build precisam de cerca de 3072 MB de RAM:

squarecloud.app

DISPLAY_NAME=Evolution API
RUNTIME=nodejs
START=npx prisma generate --schema prisma/postgresql-schema.prisma && npm run build && npm run start:prod
MEMORY=3072
VERSION=recommended
SUBDOMAIN=my-evolution-api
AUTORESTART=true

O SUBDOMAIN precisa corresponder ao endereço do SERVER_URL. Ao enviar pelo dashboard, selecione “Publicação na Web”, defina o mesmo subdomínio e cole o comando START como comando de inicialização.

O que vai no ZIP

A pasta inteira do projeto: package.json, runWithProvider.js, src/, prisma/ e os outros arquivos da release ou do repositório.
.env, com as variáveis acima.
O certificado de cliente .p12.
squarecloud.app.

Deixe de fora a node_modules/, que o npm install criou para as migrações: a Square Cloud instala as dependências no servidor.

Faça o deploy e verifique

Via dashboard

Acesse a página de upload

Acesse a página de upload e envie seu arquivo zip.

Configure seu ambiente

Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.
Se você estiver enviando um projeto web, certifique-se de selecionar “Publicação na Web” e definir um subdomínio para o seu projeto.

Faça o deploy do projeto

Por fim, clique no botão “Deploy” para hospedar seu projeto na Square Cloud. Após o deploy, você poderá monitorar o status e os registros do seu projeto no dashboard.

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. No dashboard, aguarde o status da sua aplicação mudar para em execução e verifique os registros em busca de erros de inicialização.
Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.

Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Via CLI

Para usar esse método, seu projeto precisa de um arquivo de configuração chamado squarecloud.app na raiz. Ele informa à Square Cloud como executar a sua aplicação.

Guia do arquivo de configuração

Saiba como criar o arquivo de configuração squarecloud.app que define o ambiente da sua aplicação.

Instale a CLI

Instale a CLI da Square Cloud. Se você já a tem, execute o mesmo comando para atualizá-la:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

Faça login

Execute o comando abaixo. Ele abre o seu navegador: aprove o login lá e a CLI está pronta. Não há nenhuma chave de API para copiar. Para scripts e CI, veja autenticação da CLI.

squarecloud auth login

Envie o seu projeto

Na pasta do seu projeto, execute o comando abaixo. A CLI compacta a pasta atual, deixando de fora o que o squarecloud.ignore lista, e faz o upload:

squarecloud upload

Para enviar um zip que você mesmo criou, passe-o com --file:

squarecloud upload --file <caminho/para/zip>

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. Verifique o status e os registros da sua aplicação diretamente pelo terminal:

squarecloud app status
squarecloud app logs

Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.

Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Reduza a RAM depois da primeira execução

Após a primeira execução, você pode reduzir a RAM para 1536MB ou 2048MB e definir o comando de inicialização apenas para:

npm run start:prod

Primeiro acesso

Abra https://my-evolution-api.squareweb.app/manager para acessar o gerenciador web. Entre com o seu SERVER_URL como URL do servidor e a sua AUTHENTICATION_API_KEY como chave de API global e crie a sua primeira instância do WhatsApp.

Erros comuns

Domínio personalizado

Para usar um domínio personalizado (ex.: meusite.com) no lugar da URL padrão meusite.squareweb.app, você precisa do plano Standard ou superior. A URL padrão vem do campo SUBDOMAIN no arquivo de configuração. Para conectar o seu domínio, veja como configurar seu próprio domínio.

Requisitos mínimos de RAM

Mínimo: 512MB de RAM para sites e APIs, o suficiente para um build estático no runtime estático. Para aplicações que renderizam páginas no servidor (Next.js, Nuxt, Angular SSR e similares), recomendamos pelo menos 1GB de RAM. Para aplicações maiores, aloque mais RAM para evitar que a aplicação fique sem memória e trave.

Não foi possível encontrar esse site.

Verifique se o subdomínio/domínio corresponde ao configurado no campo SUBDOMAIN ou nas configurações de domínio personalizado. Se você acabou de enviar o site, aguarde até 60 segundos para a Square liberar o primeiro acesso.

Site demorou demais para responder…

O seu servidor precisa escutar na porta 80 e no host 0.0.0.0. A Square Cloud define as variáveis de ambiente PORT (80) e HOST (0.0.0.0) na sua aplicação: leia essas variáveis no código em vez de fixar outros valores. Um servidor que escuta apenas em localhost ou 127.0.0.1 nunca recebe requisições.

A Evolution API não consegue se conectar ao banco de dados

Confira se o sslidentity aponta para o arquivo .p12 dentro do seu ZIP e se o sslpassword é a senha de exportação que você escolheu. Para outros erros de SSL/TLS, veja erros de conexão com o banco de dados.

Próximos passos

Banco de dados gerenciado

Crie o banco de dados PostgreSQL de que a Evolution API precisa.

Erros de conexão com o banco

Corrija erros de SSL/TLS e de conexão.

Bot do WhatsApp

Crie um bot de WhatsApp com whatsapp-web.js ou Baileys.

Contate-nos

Se você continuar enfrentando dificuldades técnicas, nossa equipe de suporte especializada está disponível para auxiliá-lo. Entre em contato conosco e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com 4,9/5 em 402 avaliações no Google e Trustpilot.

Bots

Sites

APIs e backends

Bancos de dados

Aplicações self-hosted

Guias

Guias de migração

Faça deploy da Evolution API (API do WhatsApp)

Introdução

Pré-requisitos

Obtenha o projeto

Configure a Evolution API

Banco de dados

Aplique as migrações

Servidor

Chave de API global

Cache Redis (opcional)

Configure a Square Cloud

O que vai no ZIP

Faça o deploy e verifique

Via dashboard

Via CLI

Guia do arquivo de configuração

Reduza a RAM depois da primeira execução

Primeiro acesso

Erros comuns

Domínio personalizado

Requisitos mínimos de RAM

Não foi possível encontrar esse site.

Site demorou demais para responder…

A Evolution API não consegue se conectar ao banco de dados

Próximos passos

Banco de dados gerenciado

Erros de conexão com o banco

Bot do WhatsApp

Contate-nos

​Introdução

​Pré-requisitos

​Obtenha o projeto

​Configure a Evolution API

​Banco de dados

​Aplique as migrações

​Servidor

​Chave de API global

​Cache Redis (opcional)

​Configure a Square Cloud

​O que vai no ZIP

​Faça o deploy e verifique

​Via dashboard

​Via CLI

Guia do arquivo de configuração

​Reduza a RAM depois da primeira execução

​Primeiro acesso

​Erros comuns

​Domínio personalizado

​Requisitos mínimos de RAM

​Não foi possível encontrar esse site.

​Site demorou demais para responder…

​A Evolution API não consegue se conectar ao banco de dados

​Próximos passos

Banco de dados gerenciado

Erros de conexão com o banco

Bot do WhatsApp

​Contate-nos

Introdução

Pré-requisitos

Obtenha o projeto

Configure a Evolution API

Banco de dados

Aplique as migrações

Servidor

Chave de API global

Cache Redis (opcional)

Configure a Square Cloud

O que vai no ZIP

Faça o deploy e verifique

Via dashboard

Via CLI

Reduza a RAM depois da primeira execução

Primeiro acesso

Erros comuns

Domínio personalizado

Requisitos mínimos de RAM

Não foi possível encontrar esse site.

Site demorou demais para responder…

A Evolution API não consegue se conectar ao banco de dados

Próximos passos

Contate-nos