Cómo migrar de una API no oficial (Evolution API, Baileys, WPPConnect) a la API oficial de WhatsApp

Actualizado el 29/10/2026

Migrar a la API oficial de WhatsApp significa cambiar la sesión de WhatsApp Web, abierta con código QR, por un número registrado en la Cloud API de Meta, al que se accede con un token y llamadas HTTP. El número tiene que salir de la app (o conectarse por coexistencia, si está en la app WhatsApp Business), los mensajes fuera de la ventana de 24 horas pasan a requerir plantillas aprobadas y los webhooks adoptan el formato de Meta. El mayor trabajo suele estar en el código que recibe los eventos y en las reglas de envío, no en el envío en sí.

Esta guía es para quien tiene una integración funcionando con Baileys, WPPConnect o el modo Baileys de Evolution API y quiere pasar a la API oficial de WhatsApp sin detener la operación.

Por qué migrar: el riesgo real de las API no oficiales

Las bibliotecas no oficiales controlan una sesión de WhatsApp Web. Para WhatsApp, eso es acceso automatizado no autorizado. Las Condiciones del servicio prohíben acceder o usar el servicio «por medios automatizados» sin autorización e incluyen los mensajes masivos y los mensajes automáticos entre los usos no permitidos. La comparación completa está en API oficial vs. API no oficial de WhatsApp.

Quien ya operó con este modelo conoce las consecuencias:

• Bloqueo del número, a veces sin relación clara con el volumen. Un número bloqueado tiene que pasar por una apelación antes de poder registrarse de nuevo, también en la Cloud API, según la documentación de números.
• Fallas después de actualizaciones de WhatsApp, que obligan a actualizar la biblioteca a las apuradas.
• Sesiones que se caen y piden escanear el QR otra vez, muchas veces por alguien con el celular en la mano.
• Ningún soporte de Meta cuando algo sale mal.

En la API oficial, el bloqueo por «usar la herramienta equivocada» deja de existir. Lo que pasa a importar es la calidad: los bloqueos y denuncias de los destinatarios afectan la calificación del número y los límites de envío.

Qué cambia al migrar

Aspecto	API no oficial	API oficial (Cloud API)
Conexión	Código QR y sesión guardada en el servidor	Token de acceso; número registrado en Meta
Envío fuera de una conversación activa	Mensaje libre	Solo plantilla aprobada
Respuesta al cliente	Libre, en cualquier momento	Libre dentro de la ventana de 24 h; después, plantilla
Identificador del contacto	JID (5584999999999@s.whatsapp.net)	wa_id (5584999999999) y, desde abril de 2026, el BSUID (user_id)
Identificador del mensaje	ID de la biblioteca	wamid.…
Eventos	Formato propio (ej.: messages.upsert)	Webhook de Meta: entry[].changes[].value
Multimedia recibida	Archivo o base64 en el evento	media_id; el archivo se descarga con otra llamada
Grupos	Acceso amplio	API de Grupos con límites (8 participantes, exige cuenta comercial oficial)
Costo	Sin cobro de Meta	Cobro por mensaje entregado

Los límites de la API de Grupos están en la documentación de grupos de Meta: los grupos exigen una cuenta comercial oficial, admiten hasta 8 participantes y no están disponibles para números conectados por coexistencia. Si tu flujo depende de grupos grandes, listas de difusión o de leer los estados de los contactos, revisa este punto antes que cualquier otro, porque la API oficial no replica esos usos.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Paso a paso de la migración

1. Haz el inventario de lo que hace la integración actual

Enumera cada flujo y clasifícalo:

• Respuesta a mensajes del cliente (atención, chatbot): sigue igual, dentro de la ventana de 24 horas.
• Mensajes iniciados por la empresa (recordatorios, avisos de cobro, avisos de entrega, campañas): se convierten en plantillas.
• Funciones sin equivalente (grupos grandes, listas de difusión, estados): necesitan otra solución.

Esa lista se convierte en tu lista de plantillas y muestra dónde va a cambiar tu producto.

2. Prepara la cuenta en Meta

Necesitas un portfolio comercial (antes Business Manager), de preferencia verificado, y un método de pago en la cuenta de mensajes, o un proveedor que te facture y cubra los cobros de Meta. La verificación influye en los límites de mensajes: los portfolios nuevos empiezan con 250 destinatarios únicos por 24 horas móviles fuera de la ventana de atención, compartidos por todos los números del portfolio, y la verificación es uno de los caminos para llegar a 2.000. La guía completa de la API oficial de WhatsApp detalla los requisitos.

3. Decide qué hacer con el número

Es el punto más delicado. Hay tres caminos:

1. Número en la app WhatsApp Business: puedes conectarlo a la API y seguir usando la app, mediante la coexistencia. Requisitos y limitaciones en Coexistencia en la API de WhatsApp.
2. Número en WhatsApp común (Messenger): hay que eliminar la cuenta de la app antes de registrar el número en la Cloud API. El historial del teléfono no pasa a la API.
3. Número nuevo: permite migrar en paralelo. Activas el número oficial, migras los flujos de a poco y apagas el anterior después.

Si el número ya está en la API oficial con otro proveedor, nada de esto aplica: Meta no admite migrar un número de un socio a otro en el nuevo modelo de cuentas, disponible de forma general desde el 23/09/2026. En su lugar, compartes tu cuenta de WhatsApp con el nuevo proveedor, como se explica en cómo cambiar de proveedor de la API de WhatsApp.

Si tu número actual ya fue bloqueado, solo podrá registrarse después de ser reactivado mediante el proceso de apelación.

Al desconectar la sesión no oficial, cierra la biblioteca antes de registrar el número en Meta. Dos conexiones intentando usar el mismo número generan errores difíciles de diagnosticar.

4. Crea y aprueba las plantillas

Para cada mensaje iniciado por la empresa, crea una plantilla con la categoría correcta: utilidad para avisos ligados a una transacción o cuenta, autenticación para códigos, marketing para promociones. Meta la revisa y puede recategorizarla. En Vectalk, se crea con el endpoint de plantillas usando un token de instancia:

{
  "name": "recordatorio_cita",
  "language": "es",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Hola {{1}}, tu cita está agendada para el {{2}}. Responde 1 para confirmar.",
      "example": { "body_text": [["María", "22/10 a las 14 h"]] }
    }
  ]
}

La plantilla queda con estado PENDING hasta su aprobación. Empieza por aquí, porque es la etapa que depende de terceros.

Si vas a enviar marketing, ten en cuenta una fecha: la Cloud API (/messages) deja de enviar mensajes de marketing el 13/10/2027, y las cuentas de mensajes creadas a partir del 13/04/2027 ya no pueden enviarlos por ahí. El camino es la Marketing Messages API.

5. Cambia la capa de envío

En la API no oficial, el envío es una llamada a una función de la biblioteca. En la oficial, es un POST HTTP. Un envío típico con Baileys:

// Antes (Baileys)
await sock.sendMessage('5584999999999@s.whatsapp.net', { text: 'Pedido confirmado' })

Pasa a ser:

// Después (API oficial vía Vectalk)
const res = await fetch('https://apis.vectalk.com.br/api/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VECTALK_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messaging_product: 'whatsapp',
    to: '5584999999999',
    type: 'text',
    text: { body: 'Pedido confirmado' },
  }),
})
const data = await res.json()
const wamid = data.messages[0].id // guárdalo para cruzarlo con los estados

El número va en formato E.164 sin el +. Guarda el wa_id que la API devuelve en contacts[0].wa_id y úsalo como clave del contacto, en lugar de reconstruir el número a partir de lo que escribió el usuario. Prevé también el BSUID: cuando un cliente adopta un nombre de usuario de WhatsApp, el número de teléfono puede dejar de llegar en los webhooks, así que el modelo de contacto debe aceptar también user_id. Más en nombres de usuario de WhatsApp y BSUID.

Antes de enviar un mensaje libre, el código necesita saber si la ventana de 24 horas está abierta. Una forma simple es registrar la hora del último mensaje recibido de cada contacto:

function ventanaAbierta(ultimoMensajeDelCliente) {
  const VEINTICUATRO_HORAS = 24 * 60 * 60 * 1000
  return Date.now() - ultimoMensajeDelCliente.getTime() < VEINTICUATRO_HORAS
}

const payload = ventanaAbierta(contacto.ultimoMensajeEn)
  ? { type: 'text', text: { body: texto } }
  : { type: 'template', template: { name: 'retomar_atencion', language: { code: 'es' } } }

6. Reescribe la recepción de eventos (webhooks)

Aquí suele estar la mayor parte del trabajo. En lugar de eventos como messages.upsert, recibes un POST con la estructura de Meta, en la que mensajes y estados llegan dentro de entry[].changes[].value:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "558430000000", "phone_number_id": "PHONE_NUMBER_ID" },
        "contacts": [{ "profile": { "name": "João" }, "wa_id": "5584988888888", "user_id": "BR.13491208655302741918" }],
        "messages": [{
          "from": "5584988888888",
          "from_user_id": "BR.13491208655302741918",
          "id": "wamid.HBgL...",
          "timestamp": "1760000000",
          "type": "text",
          "text": { "body": "Quiero reprogramar" }
        }]
      }
    }]
  }]
}

Tres cambios que merecen atención:

• Los estados llegan por separado. sent, delivered, read y failed vienen en value.statuses[], con referencia al wamid que guardaste al enviar.
• La multimedia llega por referencia. Una imagen recibida trae image.id; para descargar el archivo, usa los endpoints de multimedia.
• Los eventos pueden llegar repetidos. Meta reintenta durante hasta siete días cuando tu endpoint no responde 200, y eso puede duplicar notificaciones. Deduplica por el id del mensaje.

En Vectalk, el webhook se registra por API y puedes tener varias URL por instancia. Los detalles están en la página de webhooks de la documentación. Para ejemplos completos de servidor, idempotencia y colas, consulta Webhooks de la API de WhatsApp: guía práctica.

7. Opera en paralelo y haz el corte

Si elegiste un número nuevo, mantén los dos durante un tiempo. Pasa primero los flujos de respuesta (que no dependen de plantillas) y después los de notificación. Sigue las tasas de entrega y de falla con los webhooks de estado. Cuando las cifras estén estables, apaga la sesión anterior.

Checklist de migración

Ítem	¿Listo?
Inventario de flujos: respuesta, iniciados por la empresa, sin equivalente	☐
Portfolio comercial creado y verificación solicitada	☐
Método de pago en la cuenta de mensajes, o facturación a través del proveedor	☐
Decisión sobre el número: coexistencia, eliminación de la app o número nuevo	☐
Nombre visible aprobado	☐
Plantillas creadas por categoría y aprobadas	☐
Base de contactos con registro de opt-in	☐
Envío reescrito a POST /messages con wamid guardado	☐
Envíos de marketing planificados para la Marketing Messages API	☐
Control de la ventana de 24 horas antes de mensajes libres	☐
Modelo de contacto preparado para wa_id y BSUID	☐
Webhook con respuesta 200 rápida, cola y deduplicación	☐
Manejo de estados failed y códigos de error	☐
Descarga de multimedia por media_id	☐
Sesión no oficial cerrada antes de registrar el número	☐
Monitoreo de calidad y del límite de mensajes	☐

Consentimiento: el punto que muchas migraciones olvidan

Con la API no oficial, muchas bases de contactos se armaron sin registro de permiso. La Política de mensajería de WhatsApp Business solo permite contactar a quien te dio su número y aceptó (opt-in) recibir mensajes, y exige respetar las solicitudes de baja. Antes de enviar la primera plantilla de marketing, separa los contactos con consentimiento registrado. Escribirle a una base fría es la forma más rápida de hundir la calidad de un número recién migrado. Si tus contactos están en Brasil, también aplica la LGPD (la ley general de protección de datos de Brasil); esto no es asesoría legal.

Cómo entra Vectalk en la migración

Vectalk es un proxy gestionado de la WhatsApp Cloud API. Conectas el número mediante el registro insertado (Embedded Signup) de Meta, recibes un token de Vectalk y usas los mismos payloads de la documentación de Meta, cambiando solo la URL base y el token. Con un token de organización, una sola credencial accede a todas las cuentas conectadas; basta enviar el phone_number_id en el cuerpo de la solicitud. Eso ayuda a quien migra varios números de clientes al mismo tiempo. El cobro es una mensualidad más un saldo prepago: Vectalk coloca su propia línea de crédito en el número, cada mensaje entregado se descuenta del saldo y no necesitas registrar una tarjeta en Meta. Vectalk también ofrece coexistencia.

Para empezar, crea tu cuenta en apps.vectalk.com.br/register y sigue la guía rápida, que pide una cuenta comercial de Meta verificada para conectar mediante el registro insertado. Las dudas de cuenta se resuelven en el Centro de Ayuda (en portugués) o por contacto.

Preguntas frecuentes

¿Puedo migrar sin perder el número?

Sí, en dos escenarios. Si el número está en la app WhatsApp Business, la coexistencia lo conecta a la API sin sacarlo de la app. Si está en WhatsApp común, eliminas la cuenta de la app y registras el número en la Cloud API; el número sigue siendo tuyo, pero el historial del teléfono no pasa a la API.

¿El historial de conversaciones se migra?

En la migración tradicional, no. Con la coexistencia, Meta permite sincronizar hasta seis meses de conversaciones individuales si la empresa autoriza compartirlas, y la sincronización debe hacerse dentro de las 24 horas posteriores a la integración.

¿Evolution API no es ya oficial?

Evolution API ofrece más de un tipo de integración. El modo basado en Baileys usa WhatsApp Web y no es oficial. Cuando se configura con la Cloud API de Meta, pasa a usar la API oficial. Lo que determina el riesgo es el canal, no el nombre del proyecto.

¿Voy a pagar por mensajes que hoy son gratis?

Sí. En la API oficial, Meta cobra por mensaje entregado, según la categoría y el país del destinatario. Cada número tiene 1.000 mensajes de servicio entregados gratis al mes; desde el 01/10/2026 se cobran las plantillas de utilidad enviadas dentro de la ventana de atención; y la ventana de punto de entrada gratuito que abren los anuncios Click-to-WhatsApp puede quedar abierta hasta 7 días (las plantillas de utilidad enviadas dentro de ella siguen siendo gratis). Para destinatarios en Brasil, las tarifas desde el 01/10/2026 son R$ 0,3217 para marketing y R$ 0,0350 para utilidad, autenticación y servicio (R$ es el real brasileño); detalles en precio de la API de WhatsApp en Brasil. Para otros mercados, consulta el precio de la API de WhatsApp por país.

¿Puedo seguir usando grupos?

Con límites. La API de Grupos de Meta exige una cuenta comercial oficial, admite hasta 8 participantes por grupo y no está disponible para números en coexistencia. Los grupos grandes y las comunidades siguen fuera del alcance de la API.

---

Fuentes oficiales consultadas el 29/10/2026: Condiciones del servicio de WhatsApp, Números de teléfono comerciales, Límites de mensajes, Webhooks, API de Grupos, Evolución del modelo de cuentas, Marketing Messages API, ID de usuario en el ámbito de la empresa (BSUID), Precios, Política de mensajería de WhatsApp Business.