Despliega Evolution API (API de WhatsApp)

Introducción

Para desarrollar y alojar Evolution API en Square Cloud, es esencial seguir una secuencia estructurada de configuraciones y requisitos previos. Esta guía técnica cubrirá todo el proceso, desde la configuración inicial hasta el despliegue en producción.

Requisitos previos

Cuenta de Square Cloud: Regístrate a través de la página de registro usando tu correo electrónico.
Plan activo: Garantiza recursos dedicados y un rendimiento optimizado para tu aplicación. Consulta nuestros planes disponibles y elige el más adecuado para tus necesidades.

¿Por qué usar Evolution API?

Evolution API es una API de código abierto para WhatsApp. Gestiona varias instancias de WhatsApp en un solo lugar, mediante su gestor web o su API REST, y las conecta con herramientas como n8n, Chatwoot y Typebot.

Configurando el proyecto

Descarga el proyecto desde nuestras releases de evolutionapi-web, que ya tienen los archivos necesarios para hacer deploy en Square Cloud, o desde el repositorio oficial.

El repositorio oficial lista typescript en devDependencies. Square Cloud instala las dependencias en modo producción, sin devDependencies, así que el paso npm run build falla. Nuestra release ya lo mueve a dependencies; con el repositorio oficial, muévelo tú.

Evolution API lee un archivo .env en la raíz del proyecto al iniciar, así que este archivo va en tu ZIP. Parte del .env de nuestra release (o del .env.example del repositorio oficial) y edita las variables de abajo. Las variables definidas en la sección Variables de entorno del dashboard tienen prioridad sobre el archivo .env, lo que hace del dashboard el mejor lugar para secretos como AUTHENTICATION_API_KEY y DATABASE_CONNECTION_URI. Consulta Variables de entorno.

Configuración de la base de datos

Evolution API necesita una base de datos PostgreSQL. Puedes alojar una en Square Cloud con el plan Standard o superior: consulta cómo crear y conectar una base de datos gestionada. Tras crearla, define su URL en el .env como DATABASE_CONNECTION_URI, junto con el certificado de cliente para la conexión de PostgreSQL. Aquí tienes un ejemplo de la configuración necesaria:

.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

Evolution API se conecta mediante Prisma, que espera el certificado de cliente como archivo .p12. Descarga los archivos del certificado (.crt y .key) desde la página de la base de datos en el dashboard, conviértelos y pon el .p12 en tu proyecto:

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

La contraseña de exportación que elijas es el sslpassword de la URL, y sslidentity es la ruta al archivo .p12. Mantén el .p12 en tu ZIP, ya que la aplicación lo lee del disco. Con la variable de entorno y el certificado configurados, aplica las migraciones en tu base de datos. Desde la carpeta del proyecto en tu computadora, instala las dependencias con npm install (necesita el archivo runWithProvider.js) y ejecuta el siguiente comando:

Windows
Linux

npm run db:deploy:win

npm run db:deploy

Configuración del servidor

Como se muestra en el archivo .env.example del repositorio, define las variables del servidor: SERVER_TYPE, SERVER_PORT, SERVER_URL y el idioma.

.env

SERVER_NAME=evolution
SERVER_TYPE=http
SERVER_PORT=80
# Your application's URL: https://<subdomain>.squareweb.app, or your custom domain
SERVER_URL="https://my-evolution-api.squareweb.app"
LANGUAGE=en
# Other variables below...

Evolution API lee su puerto de SERVER_PORT (no de PORT) y sin él usa 8080, así que mantén SERVER_PORT=80. Es importante configurar una clave de API global segura para evitar accesos no autorizados. Reemplázala por un valor aleatorio largo propio: la clave de los archivos de ejemplo es pública.

.env

# Other variables...
AUTHENTICATION_API_KEY=MySuperSecureAPIKEY

Configurar Square Cloud

Crea un archivo squarecloud.app en la raíz del proyecto. El comando START genera el cliente de Prisma, compila el proyecto y lo inicia; instalar y compilar necesita unos 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

SUBDOMAIN debe coincidir con la dirección de SERVER_URL. Al subir desde el dashboard, selecciona “Publicación Web”, define el mismo subdominio y pega el comando START como comando de inicio.

Desplegando

A través del panel

Accede a la página de subida

Accede a la página de subida y sube el archivo zip de tu proyecto.

Configura tu entorno

Después de subir tu zip, deberás configurar el nombre, el archivo principal o el entorno de ejecución y otros ajustes de tu proyecto.
Si estás subiendo un proyecto web, asegúrate de seleccionar “Publicación Web” y de definir un subdominio para tu proyecto.

Despliega tu proyecto

Por último, haz clic en el botón “Deploy” para alojar tu proyecto en Square Cloud.
Tras el despliegue, puedes monitorear el estado y los logs de tu proyecto desde el panel.

Confirma que tu aplicación esté en vivo

Tu primer despliegue suele tardar menos de un minuto. En el dashboard, espera a que el estado de tu aplicación muestre “running” y revisa los logs por si hay errores de inicio.
Si desplegaste un sitio web o una API, abre https://<tu-subdominio>.squareweb.app en tu navegador: deberías ver tu aplicación respondiendo. Si desplegaste un bot, envíale un comando para confirmar que esté online.

¿La aplicación no inicia? Consulta la guía de solución de problemas para ver las causas y soluciones más comunes.

A través de la CLI

Para usar este método, tu proyecto necesita un archivo de configuración llamado squarecloud.app en su raíz. Le indica a Square Cloud cómo ejecutar tu aplicación.

Guía del archivo de configuración

Aprende a crear el archivo de configuración squarecloud.app que define el entorno de tu aplicación.

Instala la CLI

Instala la CLI de Square Cloud. Si ya la tienes, ejecuta el mismo comando para actualizarla:

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

npm install -g @squarecloud/cli@latest

Inicia sesión

Ejecuta el comando de abajo. Abre tu navegador: aprueba el inicio de sesión allí y la CLI queda lista. No hay ninguna clave de API que copiar. Para scripts y CI, consulta autenticación de la CLI.

squarecloud auth login

Sube tu proyecto

Desde la carpeta de tu proyecto, ejecuta el comando de abajo. La CLI comprime la carpeta actual en un zip, dejando fuera lo que lista squarecloud.ignore, y lo sube:

squarecloud upload

Para subir un zip que creaste tú mismo, pásalo con --file:

squarecloud upload --file <path/to/zip>

Confirma que tu aplicación esté en vivo

Tu primer despliegue suele tardar menos de un minuto. Revisa el estado y los logs de tu aplicación directamente desde la terminal:

squarecloud app status
squarecloud app logs

Si desplegaste un sitio web o una API, abre https://<tu-subdominio>.squareweb.app en tu navegador: deberías ver tu aplicación respondiendo. Si desplegaste un bot, envíale un comando para confirmar que esté online.

¿La aplicación no inicia? Consulta la guía de solución de problemas para ver las causas y soluciones más comunes.

Información adicional

Después de la primera ejecución, puedes reducir la RAM a 1536MB o 2048MB y establecer el comando de inicio únicamente como:

npm run start:prod

Sistema de caché

Puedes configurar un sistema de caché en Evolution API. Para ello, necesitarás una base de datos Redis que también puedes alojar en Square Cloud.
Para configurarlo, también necesitarás descargar el certificado y establecer la URL para conectarte. Fíjate en el esquema rediss://: las bases de datos de Square Cloud solo aceptan conexiones TLS.

.env

CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI="rediss://default:MySecurePassword@square-cloud-db-ID.squareweb.app:7170"
CACHE_REDIS_TTL=604800
# Prefix serves to differentiate data from one installation to another that are using the same redis
CACHE_REDIS_PREFIX_KEY=evolution
# Enabling this variable will save the connection information in Redis and not in the database.
CACHE_REDIS_SAVE_INSTANCES=false

Solución de problemas

Dominio personalizado

Para usar un dominio personalizado (por ejemplo, mysite.com) en lugar de la URL predeterminada mysite.squareweb.app, necesitas el plan Standard o superior. La URL predeterminada sale del campo SUBDOMAIN del archivo de configuración. Para conectar tu dominio, sigue cómo configurar tu propio dominio.

Requisitos mínimos de RAM

Mínimo: 512MB de RAM para sitios web y APIs, suficiente para un build estático en el runtime estático. Para apps que renderizan páginas en un servidor (Next.js, Nuxt, Angular SSR y similares), recomendamos al menos 1GB de RAM. Para aplicaciones más grandes, asigna más RAM para evitar que la aplicación se quede sin memoria y falle.

No se pudo encontrar este sitio.

Verifica que el subdominio/dominio coincida con lo configurado en el campo SUBDOMAIN o en la configuración del dominio personalizado. Si acabas de subir el sitio, espera hasta 60 segundos para que Square habilite el primer acceso.

El sitio tardó demasiado en responder…

Tu servidor debe escuchar en el puerto 80 y el host 0.0.0.0. Square Cloud define las variables de entorno PORT (80) y HOST (0.0.0.0) en tu aplicación: léelas en tu código en lugar de fijar otros valores. Un servidor que escucha solo en localhost o 127.0.0.1 nunca recibe solicitudes.

Próximos pasos

Base de datos gestionada

Crea la base de datos PostgreSQL que necesita Evolution API.

Errores de conexión a la base de datos

Soluciona errores de SSL/TLS y de conexión.

Bot de WhatsApp

Crea un único bot de WhatsApp con whatsapp-web.js o Baileys.

Contáctanos

Si continúas enfrentando dificultades técnicas, nuestro equipo de soporte especializado está disponible para ayudarte. Contáctanos y estaremos encantados de ayudarte a resolver cualquier problema: la calidad del soporte es una gran parte de por qué los desarrolladores califican a Square Cloud con 4.9/5 en 402 reseñas en Google y Trustpilot.

Bots

Sitios web

APIs y backends

Bases de datos

Aplicaciones autoalojadas

Guías

Guías de migración

Despliega Evolution API (API de WhatsApp)

Introducción

Requisitos previos

¿Por qué usar Evolution API?

Configurando el proyecto

Configuración de la base de datos

Configuración del servidor

Configurar Square Cloud

Desplegando

A través del panel

A través de la CLI

Guía del archivo de configuración

Información adicional

Sistema de caché

Solución de problemas

Dominio personalizado

Requisitos mínimos de RAM

No se pudo encontrar este sitio.

El sitio tardó demasiado en responder…

Próximos pasos

Base de datos gestionada

Errores de conexión a la base de datos

Bot de WhatsApp

Contáctanos

​Introducción

​Requisitos previos

​¿Por qué usar Evolution API?

​Configurando el proyecto

​Configuración de la base de datos

​Configuración del servidor

​Configurar Square Cloud

​Desplegando

​A través del panel

​A través de la CLI

Guía del archivo de configuración

​Información adicional

​Sistema de caché

​Solución de problemas

​Dominio personalizado

​Requisitos mínimos de RAM

​No se pudo encontrar este sitio.

​El sitio tardó demasiado en responder…

​Próximos pasos

Base de datos gestionada

Errores de conexión a la base de datos

Bot de WhatsApp

​Contáctanos

Introducción

Requisitos previos

¿Por qué usar Evolution API?

Configurando el proyecto

Configuración de la base de datos

Configuración del servidor

Configurar Square Cloud

Desplegando

A través del panel

A través de la CLI

Información adicional

Sistema de caché

Solución de problemas

Dominio personalizado

Requisitos mínimos de RAM

No se pudo encontrar este sitio.

El sitio tardó demasiado en responder…

Próximos pasos

Contáctanos