Migrar de Evolution API a la API oficial de WhatsApp

En resumen: para llevar un bot o una automatización de Evolution API en modo Baileys a la Cloud API oficial de Meta, conecta el número a ZapClaw con la Coexistencia, envía por la API REST de ZapClaw en lugar de /message/sendText y lee el webhook de ZapClaw en lugar de messages.upsert. El número sigue funcionando en la app de WhatsApp Business en tu celular. Abajo: los pasos, los campos de envío de texto, multimedia y plantilla y los principales campos de webhook lado a lado, y lo que no tiene equivalente en la API oficial.

ZapClaw es un gateway alojado en la Cloud API de Meta: ningún servidor de Evolution que mantener en marcha y ninguna app propia en Meta.

Plan Business: US$ 29 al mes, con números ilimitados

Empieza gratis Ver el mapeo de campos

Por qué pasar a la API oficial

Las políticas de Meta siguen aplicando en la API oficial: Meta puede restringir o desactivar una cuenta que las incumple, y la API de ZapClaw responde entonces 403 con el motivo (errores, en inglés).

Lo que necesitas para conectar

No necesitas una empresa registrada ni un negocio verificado para conectar. La lista completa.

La migración, paso a paso

  1. Primero, mapea tu código. Cambia tus llamadas de envío y tu manejador de webhook con las tablas de abajo, o pon el shim delante de tu flujo para que conserve sus llamadas de Evolution mientras lo reescribes.
  2. Haz una copia de seguridad de tus chats en la app de WhatsApp Business y revisa los requisitos de arriba.
  3. Conecta el número. Crea tu cuenta en ZapClaw y conecta el número en la ventana de Meta, desde el panel. Meta desvincula entonces todos los dispositivos vinculados a la cuenta, y la instancia de Evolution pierde su sesión. Borra la instancia después, para que nadie la vuelva a vincular escaneando su código QR y dos sistemas respondan al mismo cliente.
  4. Configura el webhook. En el panel, en Webhook, pega tu URL HTTPS pública, elige los eventos y copia la clave de firma. Marca Mensajes enviados desde la app WhatsApp Business si tu flujo leía mensajes con fromMe: true.
  5. Crea una clave de API y envía con ella en el encabezado X-API-Key a https://api.zapclaw.app. El campo from indica el número, así que una clave envía desde todos los números de la cuenta.
  6. Crea tus plantillas. Fuera de la ventana de 24 horas, y para escribir primero, Meta solo acepta una plantilla aprobada. Créalas en el panel o con POST /api/v1/send/templates, y pasa language al enviar una: el valor por defecto de la API es pt_BR.
  7. Prueba. Haz clic en Enviar evento de prueba en la página Webhook del panel, luego escribe a tu número desde otro celular y comprueba que tu flujo recibe el mensaje y responde.

Envío: las llamadas de Evolution API y su equivalente en ZapClaw

Evolution API v2 en la versión 2.3.7, la última versión estable cuando lo revisamos. Las rutas de Evolution son relativas a tu servidor de Evolution, y las de ZapClaw a https://api.zapclaw.app.

Evolution API v2 ZapClaw
Enviar texto POST /message/sendText/{instance} POST /api/v1/send/text
Enviar multimedia POST /message/sendMedia/{instance}, además de /sendWhatsAppAudio y /sendSticker POST /api/v1/send/media
Enviar una plantilla POST /message/sendTemplate/{instance} POST /api/v1/send/template
Autenticación Encabezado apikey Encabezado X-API-Key
Tu número La instancia, en la ruta from, en el cuerpo
Destinatario number: dígitos con el código de país to: solo dígitos, sin @s.whatsapp.net
Texto text en el validador de la 2.3.7, textMessage.text en el esquema de la documentación text, hasta 4,096 caracteres
Vista previa del enlace linkPreview previewUrl
Responder a un mensaje quoted.key.id replyTo: el wamid del mensaje
Tipo de multimedia mediatype type: image, video, audio, document o sticker
Archivo multimedia media: una URL o base64 link, una URL https pública, o mediaId de POST /api/v1/media
Leyenda y nombre de archivo caption, fileName caption (imagen, video, documento), filename (documento)
Nota de voz y sticker audio en /sendWhatsAppAudio, sticker en /sendSticker type audio o sticker (WebP), con link o mediaId
Campos de la plantilla name, language, components templateName, language, components
Retraso y menciones delay, mentioned, mentionsEveryOne Sin equivalente. POST /api/v1/send/typing muestra el indicador de escritura en un mensaje que recibiste.
Respuesta key.id, key.remoteJid, status 201 con message.wamid, message.to y message.status

La ubicación, las tarjetas de contacto y las reacciones van por POST /api/v1/send/location, /send/contacts y /send/reaction (referencia de la API, en inglés). El shim de más abajo aún no convierte esas llamadas: envíalas directo a ZapClaw.

Recepción: messages.upsert y su equivalente en ZapClaw

Evolution envía event, instance, data, sender y algunos campos más; las rutas de data de abajo son las de un evento messages.upsert. ZapClaw envía event, timestamp, data y account a una sola URL para todos tus números.

Evolution API v2 ZapClaw
Evento messages.upsert message.received, también en el encabezado X-ZapClaw-Event
Cuál de tus números instance, sender account.phone_number_id, account.display_phone_number
Remitente data.key.remoteJid: el número más @s.whatsapp.net data.from, solo dígitos, y data.user_id, el id permanente del contacto
Enviado por ti data.key.fromMe: true Un evento aparte, message.echo, con data.to, para mensajes enviados desde la app de WhatsApp Business o WhatsApp Web (opcional)
Id del mensaje data.key.id data.message_id, un wamid
Nombre del contacto data.pushName data.contact_name
Hora data.messageTimestamp: segundos, como número data.timestamp: segundos, como cadena
Tipo data.messageType: conversation, imageMessage, audioMessage y así sucesivamente data.type: text, image, audio, video, document, sticker y otros
Texto data.message.conversation data.text.body
Archivo multimedia data.message.mediaUrl con el almacenamiento S3 o MinIO activo, o data.message.base64 data.<type>.media_url, que descargas con tu X-API-Key
Leyenda y tipo MIME data.message.imageMessage.caption, data.message.imageMessage.mimetype data.image.caption, data.image.mime_type
Nombre de archivo data.message.documentMessage.fileName data.document.filename
Nota de voz data.message.audioMessage.ptt data.audio.voice
Mensaje citado data.contextInfo.stanzaId data.context.id
Estado de entrega messages.update, con SERVER_ACK, DELIVERY_ACK, READ o ERROR message.status, con data.status igual a sent, delivered, read o failed
Autenticación de la solicitud Ninguna por defecto. Encabezados opcionales que tú eliges, y un encabezado jwt_key se convierte en un token Authorization: Bearer firmado X-ZapClaw-Signature: un HMAC-SHA256 del cuerpo sin procesar, hecho con tu clave de firma (cómo verificarla, en inglés)

Un enlace multimedia de ZapClaw necesita tu clave de API, y Meta guarda los archivos recibidos unos 30 días, así que descarga lo que quieras conservar. Las entregas pueden llegar fuera de orden: cuando el orden importa, ordena por el sequence del nivel superior.

Lo que no tiene equivalente, y qué hacer en su lugar

Sigue usando la app de WhatsApp Business en el celular: Meta desconecta un número con Coexistencia cuya app pasa unos 14 días sin uso, y ZapClaw avisa a tu webhook con un evento account.account_update (detalles, en inglés).

Un adaptador corto

Dos funciones para Node.js 18 o más reciente, sin dependencias: la primera envía donde tu código llamaba a sendText, la segunda convierte un message.received de ZapClaw en los campos de messages.upsert que tu flujo ya lee. Comprueba el encabezado X-ZapClaw-Signature antes de confiar en un cuerpo.

// Sending: what was POST /message/sendText/{instance} with an apikey header
const sendText = async ({ number, text }) => {
  const res = await fetch('https://api.zapclaw.app/api/v1/send/text', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ZAPCLAW_API_KEY,
    },
    body: JSON.stringify({ from: process.env.ZAPCLAW_FROM, to: number, text }),
  });
  if (!res.ok) throw new Error(`ZapClaw answered ${res.status}`);
  const { message } = await res.json();
  return { key: { id: message.wamid } }; // where your code read key.id
};

// Receiving: the messages.upsert fields, taken from a message.received body
const fromZapClaw = (body) => ({
  remoteJid: `${body.data.from}@s.whatsapp.net`,
  id: body.data.message_id,
  pushName: body.data.contact_name,
  messageTimestamp: Number(body.data.timestamp),
  conversation: body.data.text ? body.data.text.body : undefined,
});

La versión completa está en GitHub: zapclaw/migrate-to-whatsapp-official-api convierte texto, multimedia, plantillas, estados de entrega y webhooks, e incluye un pequeño shim. Una llamada que no se convierte, como una ubicación, una tarjeta de contacto o una reacción, se rechaza con un código de error claro: envía esas llamadas directo por la API de ZapClaw. Apunta al shim la URL base de Evolution que usa tu flujo: reenvía a ZapClaw las llamadas que convierte y transforma los webhooks firmados de ZapClaw de nuevo en messages.upsert, para que migres primero y reescribas después. Licencia MIT.

Si usabas otras funciones de Evolution

Cuánto cuesta

Meta te cobra directamente las tarifas de mensajes de WhatsApp, sin margen de ZapClaw. Todos los planes y precios.

Ver también

Fuentes

Revisado el 15 de octubre de 2026. Evolution API cambia entre versiones, así que revisa la documentación de la versión que usas.

Lleva tus flujos de Evolution a la API oficial

Empieza en el plan gratuito: un número, sin tarjeta. Pasa al plan Business cuando necesites más números o más mensajes.

Empieza gratis Leer la documentación del webhook