Evolution API, Baileys y afines: cuándo vale la pena y cuándo se vuelve un problema
Por José Pedro · Cofundador de CRPRO
Evolution API envuelve a Baileys, la librería no oficial que habla el protocolo de WhatsApp Web, en una capa REST. Vale la pena para un número secundario o un caso de uso interno con alguien de guardia. Se vuelve un problema en el momento en que le cuelgas el número principal y la facturación de la empresa. Mira la comparación de costo real y cuándo tiene sentido cada camino.
Evolution API es una capa HTTP no oficial encima de Baileys, la librería en TypeScript que habla el protocolo de WhatsApp Web sin pasar por Meta. Vale la pena cuando el número es secundario, el caso de uso es interno o experimental, y hay alguien para arreglarlo cuando se rompa. Se convierte en un problema cuando le cuelgas la facturación de la empresa: la cuenta no llega en un mensaje cobrado, llega en horas de ingeniería, guardia de madrugada y un número que puede desaparecer sin ningún aviso.
¿Qué son Evolution API, Baileys y las librerías parecidas?
Son tres capas distintas, y buena parte de la confusión viene de tratar a las tres como si fueran una sola cosa.
| Capa | Qué es | Cómo se conecta |
|---|---|---|
| Baileys | Librería en TypeScript que implementa el protocolo multidispositivo de WhatsApp Web | WebSocket directo, sin navegador y sin Chromium; emparejamiento por código QR o código |
| Evolution API | Servicio que envuelve a Baileys en REST: corre en Docker, crea instancias, entrega eventos por webhook | Baileys por debajo y, en versiones recientes, también la Cloud API oficial de Meta — lo que la convierte en un enrutador de proveedores, no solo en un wrapper |
| whatsapp-web.js, Venom, WPPConnect | Librerías que automatizan un Chromium de verdad | Navegador real: más fiel al cliente oficial, mucho más caro en RAM |
Ninguna es oficial, ninguna tiene contrato con Meta. Todas leen el protocolo del cliente web — tu operación depende de un objetivo que se mueve y no avisa cuándo se va a mover.
¿Qué resuelven de verdad estas librerías?
No es poco, y vale la pena listarlo antes de hablar del precio escondido:
| Lo que ganas | Por qué |
|---|---|
| R$0,00 de tarifa por mensaje (no hay cobro de Meta en el camino por código QR, situación en agosto de 2026) | Pagas infraestructura, no pagas tarifa |
| Sin plantilla y sin aprobación | Nada de someter texto y esperar revisión para mandar un aviso |
| Sin ventana de 24 horas | Mandas cuando quieres, a quien quieras, técnicamente |
| Funciones que la Cloud API no tiene | Grupos, estados, presencia "escribiendo", historial del dispositivo |
| El número sigue en el celular | No hay migración: es el mismo número, emparejado como un dispositivo más |
| Se levanta en minutos | Sin Business Manager, sin verificación de empresa, sin BSP |
Este último ítem es lo que más mueve a la gente en la práctica. En la API oficial, el número migrado sale de la aplicación — quien depende de grupos, estados o de atender desde el celular pierde eso.
¿Por qué se cae la sesión y quién reconecta el número?
La sesión es un conjunto de claves criptográficas que necesita sobrevivir a un reinicio, un deploy y la caída de un contenedor. El comportamiento por defecto de la librería guarda esto en un archivo; en un contenedor efímero, eso es pérdida de sesión garantizada. Vas a querer ese estado en Postgres o Redis, cifrado en reposo — es literalmente la credencial de WhatsApp de un cliente.
La reconexión no es un error raro, es rutina: un celular sin internet por demasiado tiempo, un cierre de sesión por error, un cambio de protocolo del lado de Meta. Y cuando cae, alguien tiene que escanear un código QR nuevo. El código QR necesita una persona, no un script — no hay forma de automatizar el escaneo de un código que aparece en tu pantalla y necesita apuntarse al celular correcto. Esa es la primera pregunta que tumba un proyecto en el papel: ¿quién hace esto a las 3am de un domingo?
Una versión fija contra un objetivo que se mueve
Cuando WhatsApp cambia algo, tu librería se rompe hasta que alguien en GitHub haga el commit. No hay fecha, no hay SLA, no hay ticket que abrir. La corrección que arregla el problema llega obligatoria y sin planificar — y en el camino aparecen los síntomas conocidos de quien opera esto: medios que no se descargan, un mensaje atascado en "pendiente", una sesión de cifrado desincronizada para un contacto específico.
La defensa posible es de proceso, no de contrato: fija la versión de la librería, mantén un ambiente canario que recibe la actualización antes que producción, y ten una ruta de salida hacia otro proveedor diseñada antes de necesitarla.
¿La API oficial elimina el riesgo de baneo?
No. Esta es la comparación mal hecha en los dos sentidos. Meta mantiene el campo waba_ban_state en el webhook account_update, con valores DISABLE, SCHEDULE_FOR_DISABLE y REINSTATE, y el error 368 existe justamente para cuenta restringida. Un número en la API oficial puede ser baneado — quien promete inmunidad está vendiendo humo.
Lo que cambia no es que exista el riesgo, es cuánto de él puedes ver. En el camino por código QR, la sanción llega sin métrica previa, sin aviso y sin proceso con plazo. En la API oficial, existe medición continua y notificación antes del cierre. Es la diferencia entre perder el número por sorpresa y ver el indicador ponerse amarillo con tiempo para reaccionar.
Lo que da a cambio la API oficial: aviso, medición y apelación
| Código QR / Baileys | API oficial | |
|---|---|---|
| Aviso antes de la sanción | Ninguno | Notificación por correo antes del cierre |
| Medición de calidad | No existe para ti | Quality rating verde/amarillo/rojo por número, calculado de forma ponderada sobre los últimos 7 días (criterio documentado por Meta, verificado en agosto de 2026), visible en el WhatsApp Manager y por la API |
| Escalamiento | Directo al cierre | Restricción gradual antes del cierre |
| Apelación | Formulario genérico, sin plazo | Apelación formal a través del Business Manager |
Súmale a esto un detalle técnico que casi nadie nota: en la API oficial, mandar fuera de la ventana de 24 horas es imposible — la llamada devuelve el error 131047 y solo una plantilla reabre la conversación (regla vigente en agosto de 2026). El sistema te protege de ti mismo. Con Baileys, nada impide el envío: el freno que Meta implementaría se convierte en responsabilidad de tu código. Y una librería no oficial no es lo mismo que una app modificada — GB WhatsApp y WhatsApp Plus violan los Términos de forma explícita —, pero tampoco está avalada por nadie.
Infraestructura, estado y observabilidad: qué cambia de tu lado
Una instancia de Baileys tiene estado, lo que tumba la suposición cómoda de levantar réplicas detrás de un balanceador de carga: cada número vive en un proceso específico, y el enrutamiento necesita saberlo. En la práctica terminas con:
- un healthcheck que prueba la conexión de verdad, no un
200 OKde HTTP; - una cola de envío con backoff y jitter, nunca un bucle
forcon unsleepfijo; - un webhook idempotente por id de mensaje, porque la reentrega ocurre;
- una alerta sobre el evento de desconexión, con alguien de guardia del otro lado;
- un respaldo del estado de autenticación con restauración probada — una restauración no probada es un respaldo imaginario.
Y la LGPD: la sincronización trae el historial del dispositivo a tu base de datos, y te convertiste en responsable de datos personales que tal vez no planeabas guardar.
¿Cuánto cuesta de verdad correr Baileys?
La comparación honesta no es "R$0,00 contra la tarifa de Meta". Es (horas de ingeniería por mes × tu costo por hora) + infraestructura + costo de indisponibilidad × probabilidad contra la factura de la API oficial con tu mezcla real de mensajes.
Si tienes un equipo de software, ese primer término es pequeño y la cuenta suele cerrar a favor del código QR. Si contrataste a un freelancer para levantar el Docker y se fue, el término es grande y llega concentrado en el peor día posible — normalmente un viernes de campaña. El error clásico es medir solo el costo de implementación, que es bajo en cualquier escenario, e ignorar el costo de mantenimiento, que es el que se repite cada mes.
¿Cuándo vale la pena usar Evolution API o Baileys?
- Prototipo y validación. Gastar semanas en verificación de empresa para descubrir que el flujo era malo es el peor negocio.
- Uso interno. Alerta de sistema, bot en un grupo interno, notificación de deploy. Nadie va a denunciarte, el número es secundario, una caída molesta pero no cuesta una venta.
- Lo que la Cloud API no hace. Grupos y estados no existen en la API oficial. Si ese es el caso de uso, no hay elección que hacer.
- Volumen alto de atención receptiva con equipo técnico propio. Este argumento se volvió más fuerte: desde el 1 de octubre de 2026, Meta cobra por mensaje también los mensajes de servicio y las plantillas de utilidad enviados en respuesta al usuario dentro de la ventana de atención de 24 horas (hasta el 30/09/2026 eran gratuitos). La tarifa de servicio está en la tabla de precios vigente de Meta, y quien tiene muchos mensajes por conversación debería rehacer la cuenta con ella antes de decidir. Hay un post entero sobre eso en cuándo no migrar a la API oficial.
¿Cuándo se vuelve un problema Evolution API?
- Es el número principal de la empresa. Un baneo sin aviso en el número que está en el sitio web, en la tarjeta y en Google es un evento de continuidad del negocio, no un incidente de TI.
- Marketing saliente a escala. El peor caso posible. Enviar a una lista fría por Baileys es el camino más corto para perder el número, sin aviso y sin apelación. Si el objetivo es una campaña, lee esto antes — la política exige opt-in.
- Nadie de guardia. Si la respuesta a "quién escanea el código QR a las 3am de un domingo" es silencio, la arquitectura ya falló en el papel.
- Un contrato o una auditoría exige un canal oficial. Algunos sectores no aceptan nada fuera de la API oficial, y ningún argumento técnico le gana a esa cláusula.
Se pueden usar los dos — y normalmente es la respuesta correcta
La elección no tiene que ser exclusiva por empresa, solo por número. Un número en la API oficial para campañas con opt-in, plantilla aprobada y quality rating monitoreado. Un número en código QR para el equipo interno, para grupos, para lo que la oficial no cubre. Y si el código QR va a estar en la primera línea, ten un número de respaldo ya calentado y un modelo de datos que permita cambiar de proveedor sin reescribir el CRM.
CRPRO opera en los dos modos precisamente por esto — API oficial vía BSP y conexión por código QR, con la misma atención multiagente y el mismo historial encima. Si estás diseñando esta arquitectura ahora mismo, puedes probar los dos caminos antes de elegir.
Preguntas frecuentes
¿Evolution API está permitida por WhatsApp?
No es oficial ni está homologada. Es una implementación no autorizada del protocolo de WhatsApp Web, en la misma familia que Baileys, Venom y WPPConnect. Funciona, se usa ampliamente y no tiene aval de Meta — lo que significa que operas sin contrato y sin soporte del otro lado.
¿Usar Evolution API banea el número?
La herramienta en sí no es lo que dispara el baneo; el comportamiento sí. Pero en código QR, la sanción llega sin aviso previo, sin quality rating visible y sin apelación con plazo. En la API oficial el baneo también es posible — el campo waba_ban_state y el error 368 existen para eso —, pero viene con aviso, medición y proceso.
¿Evolution API es más barata que la API oficial?
Por mensaje, sí: no pagas la tarifa de Meta. En total, depende de cuánto vale tu hora. Suma infraestructura, mantenimiento de sesión, actualizaciones no planeadas y el costo esperado de estar fuera de línea. Si tienes equipo técnico, suele ganar. Si no lo tienes, el ahorro aparece en la factura equivocada.
¿Cuál es la diferencia entre Baileys y whatsapp-web.js?
Baileys habla el protocolo directo por WebSocket, sin navegador — más liviano y más rápido. whatsapp-web.js (y Venom, y WPPConnect) automatiza un Chromium real — más pesado en memoria, pero más cercano al comportamiento del cliente oficial. Los dos se rompen cuando WhatsApp cambia algo; lo que cambia es el tipo de ruptura.
¿Puedo usar Evolution API y la API oficial en el mismo número?
No al mismo tiempo. Un número migrado a la API oficial sale de la aplicación, y es la Cloud API la que responde por él desde entonces. El arreglo viable es tener números distintos para propósitos distintos, bajo el mismo CRM.
¿En cuánto tiempo se recupera el quality rating?
El indicador se recalcula sobre los últimos 7 días de forma ponderada, así que detener la práctica que generó bloqueos de usuarios no devuelve el verde el mismo día: toma algunos días de mejor comportamiento hasta que la ventana de cálculo lo refleje. Por eso el indicador funciona como alerta anticipada, no como panel de reacción inmediata.