Migrar de WAHA a la API oficial de WhatsApp

En resumen: para llevar un bot o una automatización de WAHA 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 /api/sendText y lee el webhook de ZapClaw en lugar del evento message de WAHA. El número sigue funcionando en la app de WhatsApp Business en tu celular. Abajo: los pasos, los campos de envío de texto y multimedia 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 ni sesión de WAHA 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 WAHA mientras lo reescribes.
  2. Revisa el número. La Coexistencia conecta números que funcionan en la app de WhatsApp Business, no en WhatsApp normal. Haz una copia de seguridad de tus chats en la app 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, incluida la sesión de WAHA. Detén o borra la sesión en WAHA después, para que nadie vuelva a escanear 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 escuchaba message.any para tus propios mensajes.
  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 WAHA y su equivalente en ZapClaw

Las rutas de WAHA son relativas a tu servidor de WAHA, y las de ZapClaw a https://api.zapclaw.app.

WAHA ZapClaw
Enviar texto POST /api/sendText POST /api/v1/send/text
Enviar multimedia /api/sendImage, /api/sendVideo, /api/sendVoice, /api/sendSticker, /api/sendFile POST /api/v1/send/media con type image, video, audio, sticker o document
Autenticación Encabezado X-Api-Key Encabezado X-API-Key, con una clave de ZapClaw
Tu número session, en el cuerpo from, en el cuerpo
Destinatario chatId: el número más @c.us to: el número, solo dígitos
Texto text text, hasta 4,096 caracteres
Vista previa del enlace linkPreview previewUrl
Responder a un mensaje reply_to replyTo: el wamid del mensaje
Archivo multimedia file.url, o file.data en base64, con file.mimetype link, una URL https pública, o mediaId de POST /api/v1/media
Nombre de archivo file.filename filename (documento)
Leyenda caption caption (imagen, video, documento)
Conversión de formato convert, asNote Sin equivalente: envía un formato que WhatsApp acepte
Menciones mentions Sin equivalente

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: el evento message y su equivalente en ZapClaw

WAHA envía un sobre con event, session, me y payload; las rutas de payload de abajo son las de un evento message. ZapClaw envía event, timestamp, data y account a una sola URL para todos tus números.

WAHA ZapClaw
Evento message; message.any incluye también los tuyos message.received; tus mensajes enviados desde la app llegan como message.echo (opcional)
Cuál de tus números session, me.id account.phone_number_id, account.display_phone_number
Remitente payload.from: el número más @c.us data.from, solo dígitos, y data.user_id, el id permanente del contacto
Enviado por ti payload.fromMe El evento message.echo, con data.to
Id del mensaje payload.id data.message_id, un wamid
Nombre del contacto No está en el payload documentado; va en el _data propio del motor data.contact_name
Hora payload.timestamp: segundos en los ejemplos de la documentación data.timestamp: segundos, como cadena
Texto payload.body, que lleva la leyenda en los archivos multimedia data.text.body, o data.<type>.caption en los archivos multimedia
Tiene multimedia payload.hasMedia data.type es image, audio, video, document o sticker
Archivo multimedia payload.media.url, que descargas con tu X-Api-Key data.<type>.media_url, que descargas con tu X-API-Key
Tipo MIME y nombre de archivo payload.media.mimetype, payload.media.filename data.<type>.mime_type, data.document.filename
Mensaje citado payload.replyTo.id data.context.id
Estado de entrega message.ack, con payload.ackName igual a ERROR, PENDING, SERVER, DEVICE, READ o PLAYED message.status, con data.status igual a failed, sent, delivered o read
Autenticación de la solicitud Opcional: X-Webhook-Hmac, un HMAC SHA-512 del cuerpo, cuando la sesión tiene una clave Siempre: 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 /api/sendText, la segunda convierte un message.received de ZapClaw en los campos de payload que tu flujo ya lee. Comprueba el encabezado X-ZapClaw-Signature antes de confiar en un cuerpo.

// Sending: what was POST /api/sendText with an X-Api-Key header
const sendText = async ({ chatId, 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: chatId.replace(/@c\.us$/, ''),
      text,
    }),
  });
  if (!res.ok) throw new Error(`ZapClaw answered ${res.status}`);
  return (await res.json()).message; // message.wamid is the new message id
};

// Receiving: the payload of a WAHA message event, taken from a message.received body
const MEDIA = ['image', 'audio', 'video', 'document', 'sticker'];
const fromZapClaw = (body) => {
  const d = body.data;
  const media = MEDIA.includes(d.type) ? d[d.type] : null;
  return {
    from: `${d.from}@c.us`,
    fromMe: false,
    id: d.message_id,
    timestamp: Number(d.timestamp),
    body: d.text ? d.text.body : (media ? media.caption || '' : ''),
    hasMedia: Boolean(media),
    media: media ? { url: media.media_url, mimetype: media.mime_type } : null,
  };
};

La versión completa está en GitHub: zapclaw/migrate-to-whatsapp-official-api convierte texto, multimedia, 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 WAHA que usa tu flujo: reenvía a ZapClaw las llamadas que convierte y transforma los webhooks firmados de ZapClaw de nuevo en eventos message, message.any y message.ack, para que migres primero y reescribas después. Licencia MIT.

Si tu caso es distinto

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. Los campos de WAHA pueden variar según el motor, así que revisa la documentación del motor que usas.

Lleva tus flujos de WAHA 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