Cómo usar un proxy en WPPConnect (Chromium / Puppeteer)

WPPConnect levanta una sesión de WhatsApp Web dentro de un Chromium controlado. El origen por defecto es la IP de la máquina. Varias session en el mismo servidor, sin un proxy por instancia, son varios números en la misma dirección.

Esto no es el mismo mecanismo que Baileys. Copiar socks-proxy-agent a WPPConnect no conecta el navegador al proxy.

Objetivo de esta guía

Hacer que cada sesión salga por una IPv4 dedicada propia, sin mezclar credenciales entre clientes.

Requisitos previos

Credenciales en el panel de ProxyBox (host, puerto HTTP, usuario, contraseña)
La prueba de IP del panel en verde, o el cURL devolviendo una dirección
Una IP por sesión independiente
El paquete @wppconnect-team/wppconnect ya instalado en el proyecto

Paso 1: proxy HTTP en Chromium

Chromium acepta --proxy-server sin usuario ni contraseña en la URL. La autenticación va después.

import wppconnect from '@wppconnect-team/wppconnect'

const proxyHost = 'p1.ejemplo.com'
const proxyPort = 8000
const proxyUser = 'tu-usuario'
const proxyPass = 'tu-contrasena'

const client = await wppconnect.create({
  session: 'cliente-a',
  puppeteerOptions: {
    args: [`--proxy-server=http://${proxyHost}:${proxyPort}`],
  },
})

Comprueba en tu versión si la opción se llama puppeteerOptions o browserArgs. El efecto es el mismo: el proceso de Chrome tiene que nacer ya apuntando a host:puerto.

Paso 2: autenticación (usuario y contraseña)

Chromium no lee http://usuario:contraseña@host:puerto de forma fiable. Una vez que el navegador existe, autentica la página:

const page = client.page // el nombre del accessor varía; compruébalo en el client de tu versión
await page.authenticate({
  username: proxyUser,
  password: proxyPass,
})

Si tu versión de WPPConnect no expone page de forma estable, el patrón de producción es un reenviador local:

npm install proxy-chain

import ProxyChain from 'proxy-chain'

const anonymized = await ProxyChain.anonymizeProxy(
  `http://${proxyUser}:${proxyPass}@${proxyHost}:${proxyPort}`
)

await wppconnect.create({
  session: 'cliente-a',
  puppeteerOptions: {
    args: [`--proxy-server=${anonymized}`],
  },
})

El navegador habla con 127.0.0.1 sin contraseña; proxy-chain inyecta la credencial en el proxy real. Cierra el proxy anonimizado al apagar la sesión para no dejar procesos colgados.

Paso 3: una sesión, una IP

const cuentas = [
  { session: 'cliente-a', host: 'p1.ejemplo.com', user: 'user_a', pass: 'pass_a' },
  { session: 'cliente-b', host: 'p2.ejemplo.com', user: 'user_b', pass: 'pass_b' },
]

Cada objeto se convierte en un create() con el --proxy-server de ese host. Reutilizar la misma IP en dos session anula el motivo de tener dos números.

Verificación

Panel de ProxyBox → prueba del proxy → el país que elegiste al comprar.
Con la sesión abierta, un verificador de IP en una pestaña del mismo Chromium tiene que devolver la IP contratada, no la del VPS.
Dos números, dos pruebas, dos direcciones.

Errores comunes

Los dos números salen con la misma IP. La segunda instancia heredó el host de la primera, o Chromium arrancó sin --proxy-server.

407 / proxy authentication required. La contraseña no llegó al proxy: page.authenticate no se ejecutó, o proxy-chain tiene una URL mal formada (un espacio al pegar). Ver error 407.

La sesión sale por el VPS aunque pasaste los args. Pasaste browserArgs en una clave que tu versión ignora. Registra process.spawnargs de Chrome o abre chrome://version en el navegador de la sesión.

La sesión se cae con el proxy funcionando. El origen está bien; investiga el estado de autenticación, la versión de WhatsApp Web y el dispositivo. El proxy no sustituye nada de eso.

SOCKS5 "porque en Baileys funciona". En Chromium, empieza por HTTP. SOCKS5 entra solo con un reenviador, no como primer intento.

Lo que el proxy no resuelve

El proxy controla el origen de la conexión. No controla las políticas de WhatsApp, los límites de envío ni las denuncias de los destinatarios. Las causas de bloqueo más comunes están en número bloqueado en la API de WhatsApp.

Después de configurar

Baileys si tu stack es socket en Node, no Chromium
Evolution API si mezclas las dos
Buenas prácticas con IP dedicada
Proxy para Evolution API si todavía vas a comprar la IP

IPv4 internacional

IPv4 dedicado y fijo en el país que elijas en el checkout. Mismo precio en todos los países, HTTP y SOCKS5, renovación de la misma dirección.

1 IP / mes

US$ 3.49 por IP / mes

Contratar ahora

Hacer una pregunta

Preguntas frecuentes

¿WPPConnect usa el mismo truco que Baileys (socks-proxy-agent)?

No. Baileys es WebSocket en Node. WPPConnect levanta Chromium mediante Puppeteer. El proxy va en los argumentos del navegador y, cuando hace falta usuario y contraseña, en la autenticación de la página o en un proxy-chain local.

¿HTTP o SOCKS5 en WPPConnect?

HTTP/HTTPS es el camino estable en Chromium. Chromium no admite SOCKS5 con contraseña; si tu operación exige SOCKS, usa un reenviador local (proxy-chain) que el navegador ve como HTTP sin autenticación.

¿Una IP para todo el panel?

Solo si todos los números son la misma unidad de riesgo. Los números de clientes distintos exigen sesiones distintas y, por tanto, IPs distintas.

¿Qué pruebo antes de abrir un ticket?

La prueba de IP del panel de ProxyBox o el cURL de la documentación. Si eso falla, no es WPPConnect. Si pasa y la sesión se cae, el diagnóstico pasa al estado de autenticación, la versión y el dispositivo.

Proxy en WPPConnect