Quien levanta Evolution API en un VPS se enfrenta a un problema que casi nunca se diagnostica bien: la IP del proveedor de nube la comparten cientos de proyectos y suele arrastrar un mal historial.
Esta guía muestra cómo enrutar las instancias por una IP dedicada del país de tus números.
El problema de la IP del VPS
Cuando levantas Evolution API en un proveedor de nube, la IP pública de esa máquina pertenece a un bloque de datacenter. De ahí se derivan dos hechos:
- El bloque es compartido. Otros clientes del mismo proveedor usan direcciones vecinas, y el historial de ese rango no depende solo de tu uso.
- La geolocalización apunta al datacenter. Si el VPS está en Europa o en Estados Unidos y tus números son de México o de Colombia, esos números se conectan desde fuera de su país.
Enrutar por un proxy dedicado del país de los números resuelve las dos cosas: la salida pasa a ser una dirección exclusiva tuya, con una geolocalización coherente con el número. El país se elige en el checkout, que muestra los países disponibles para cada tipo de IP; los precios están en precios.
Antes de empezar
Copia del panel, en Mis proxies, el host, el puerto SOCKS5, el usuario y la contraseña.
Monta la cadena de conexión:
socks5://usuario:[email protected]:1080
Si la contraseña contiene @, :, / o #, codifica el carácter: @ pasa a %40, por ejemplo. Dentro de una URL, la @ es justo el separador entre la credencial y el host, así que una contraseña con @ rompe la cadena.
Opción 1: proxy por instancia (recomendada)
Es la configuración correcta para operaciones con más de un número: cada instancia sale por su propia dirección.
Al crear la instancia, indica los campos del proxy en el cuerpo de la petición:
curl -X POST https://tu-evolution.com/instance/create \
-H "apikey: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instanceName": "cliente-a",
"integration": "WHATSAPP-BAILEYS",
"proxyHost": "p1.ejemplo.com",
"proxyPort": "1080",
"proxyProtocol": "socks5",
"proxyUsername": "tu-usuario",
"proxyPassword": "tu-contrasena"
}'
Para actualizar el proxy de una instancia que ya existe:
curl -X POST https://tu-evolution.com/proxy/set/cliente-a \
-H "apikey: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"host": "p1.ejemplo.com",
"port": "1080",
"protocol": "socks5",
"username": "tu-usuario",
"password": "tu-contrasena"
}'
Los nombres exactos de los campos cambian entre versiones de Evolution. Confírmalos en la documentación de la versión que usas; la estructura (host, puerto, protocolo, usuario, contraseña) es siempre la misma.
Opción 2: proxy global por variable de entorno
Si todas las instancias deben salir por la misma dirección (por ejemplo, con un único cliente), defínelo en el entorno:
PROXY_HOST=p1.ejemplo.com
PROXY_PORT=1080
PROXY_PROTOCOL=socks5
PROXY_USERNAME=tu-usuario
PROXY_PASSWORD=tu-contrasena
En Docker Compose:
services:
evolution-api:
image: atendai/evolution-api:latest
environment:
- PROXY_HOST=p1.ejemplo.com
- PROXY_PORT=1080
- PROXY_PROTOCOL=socks5
- PROXY_USERNAME=tu-usuario
- PROXY_PASSWORD=tu-contrasena
Cuidado con esta opción cuando atiendes a varios clientes: todos los números pasan a compartir el mismo origen de red, que es justo lo que querías evitar.
Verifica antes de conectar el número
Valida el proxy antes de generar el código QR. Desde el mismo servidor donde corre Evolution:
curl -x socks5h://usuario:[email protected]:1080 https://ipinfo.io/json
La respuesta tiene que mostrar la IP contratada y el código del país que elegiste (por ejemplo, MX o CO). Si muestra la IP del VPS, el proxy no se está aplicando y no tiene sentido conectar el número todavía. Más pruebas en probar el proxy.
Dimensionamiento: cuántas IPs
| Escenario | Configuración |
|---|---|
| 1 número | 1 IPv4 dedicada |
| Varios números, mismo cliente | 1 IP por número, o 1 IP compartida si son de la misma operación |
| Varios clientes | Como mínimo, 1 IP por cliente |
| Agencia con muchos números | 1 IP por número en los casos críticos |
La cuenta es sencilla: compara el coste de una IP dedicada con lo que te cuesta perder un número en producción.
Problemas comunes
La instancia no conecta después de configurar el proxy: prueba el proxy con curl desde el propio servidor. Si curl falla, es la credencial o el puerto. Si funciona, es la configuración en Evolution.
No aparece el código QR: Evolution no consiguió establecer la conexión de salida. Comprueba que usaste el puerto de SOCKS5 y no el de HTTP.
El número se conecta y se cae en minutos: puede ser una sesión corrupta (borra y vuelve a crear la instancia), una versión desactualizada de la biblioteca o un uso simultáneo del proxy por encima de lo contratado.
Error de autenticación en el proxy: contraseña con caracteres especiales sin codificar dentro de la cadena de conexión.
Lo que el proxy resuelve aquí
El proxy controla el origen de la conexión: dirección exclusiva, geolocalización coherente con el número e independencia entre instancias.
No controla las políticas de WhatsApp, los límites de envío, la calidad del número, el contenido de los mensajes ni las denuncias de los destinatarios. Un número bloqueado por su patrón de envío no es un problema de red, y ningún proxy lo corrige. Las causas más comunes están en número bloqueado en la API de WhatsApp.
Si usas Baileys directamente, sin Evolution, mira la guía de Baileys. Si todavía no tienes la IP, mira el proxy para Evolution API.