Migrate from WAHA to the official WhatsApp API

In short: to move a bot or an automation from WAHA to Meta's official WhatsApp Cloud API, connect the number to ZapClaw through Coexistence, send through ZapClaw's REST API instead of /api/sendText, and read ZapClaw's webhook instead of WAHA's message event. The number keeps working in the WhatsApp Business app on your phone. Below: the steps, the text and media send fields and the main webhook fields side by side, and what has no equivalent on the official API.

ZapClaw is a hosted gateway on Meta's Cloud API: no WAHA server or session to keep running and no Meta app of your own.

Business plan: US$ 29 per month, with unlimited numbers

Start for free See the field mapping

Why move to the official API

Meta's policies still apply on the official API: Meta can restrict or disable an account that breaks them, and ZapClaw's API then answers 403 with the reason (errors).

What you need to connect

You do not need a company tax ID or a verified business to connect. The full checklist.

The move, step by step

  1. Map your code first. Change your send calls and your webhook handler with the tables below, or put the shim in front of your flow so it keeps its WAHA calls while you rewrite it.
  2. Check the number. Coexistence connects numbers that run on the WhatsApp Business app, not on regular WhatsApp. Back up your chats in the app and check the requirements above.
  3. Connect the number. Create your ZapClaw account and connect the number in Meta's window from the dashboard. Meta then unlinks every linked device from the account, the WAHA session included. Stop or delete the session in WAHA afterwards, so nobody scans its QR code again and two systems answer the same customer.
  4. Set the webhook. In the dashboard, under Webhook, paste your public HTTPS URL, pick the events and copy the signing secret. Tick Messages sent from the WhatsApp Business app if your flow listened to message.any for your own messages.
  5. Create an API key and send with it in the X-API-Key header to https://api.zapclaw.app. The from field names the number, so one key sends from every number of the account.
  6. Create your templates. Outside the 24-hour window, and to write first, Meta accepts only an approved template. Create them in the dashboard or with POST /api/v1/send/templates, and pass language when you send one: the API's default is pt_BR.
  7. Test. Press Send test event on the dashboard's Webhook page, then write to your number from another phone and check that your flow receives the message and replies.

Sending: WAHA calls and their ZapClaw equivalent

WAHA's paths are relative to your WAHA server, and ZapClaw's to https://api.zapclaw.app.

WAHA ZapClaw
Send text POST /api/sendText POST /api/v1/send/text
Send media /api/sendImage, /api/sendVideo, /api/sendVoice, /api/sendSticker, /api/sendFile POST /api/v1/send/media with type image, video, audio, sticker or document
Authentication X-Api-Key header X-API-Key header, with a ZapClaw key
Your number session, in the body from, in the body
Recipient chatId: the number plus @c.us to: the number, digits only
Text text text, up to 4,096 characters
Link preview linkPreview previewUrl
Reply to a message reply_to replyTo: the wamid of the message
Media file file.url, or file.data in base64, with file.mimetype link, a public https URL, or mediaId from POST /api/v1/media
File name file.filename filename (document)
Caption caption caption (image, video, document)
Format conversion convert, asNote No equivalent: send a format WhatsApp accepts
Mentions mentions No equivalent

Location, contact cards and reactions go through POST /api/v1/send/location, /send/contacts and /send/reaction (API reference). The shim further down does not convert those calls yet: send them straight to ZapClaw.

Receiving: the message event and its ZapClaw equivalent

WAHA posts an envelope with event, session, me and payload; the payload paths below are those of a message event. ZapClaw posts event, timestamp, data and account to one URL for all your numbers.

WAHA ZapClaw
Event message; message.any also includes your own message.received; your own messages from the app come as message.echo (opt-in)
Which of your numbers session, me.id account.phone_number_id, account.display_phone_number
Sender payload.from: the number plus @c.us data.from, digits only, and data.user_id, the contact's durable id
Sent by you payload.fromMe The message.echo event, with data.to
Message id payload.id data.message_id, a wamid
Contact name Not in the documented payload; it sits in the engine's own _data data.contact_name
Time payload.timestamp: seconds in the documentation's examples data.timestamp: seconds, as a string
Text payload.body, which holds the caption on media data.text.body, or data.<type>.caption on media
Has media payload.hasMedia data.type is image, audio, video, document or sticker
Media file payload.media.url, downloaded with your X-Api-Key data.<type>.media_url, downloaded with your X-API-Key
Mime type and file name payload.media.mimetype, payload.media.filename data.<type>.mime_type, data.document.filename
Quoted message payload.replyTo.id data.context.id
Delivery status message.ack, with payload.ackName set to ERROR, PENDING, SERVER, DEVICE, READ or PLAYED message.status, with data.status set to failed, sent, delivered or read
Request authentication Optional: X-Webhook-Hmac, an HMAC SHA-512 of the body, when the session has a key Always: X-ZapClaw-Signature, an HMAC-SHA256 of the raw body, keyed with your signing secret (how to verify it)

A media link from ZapClaw needs your API key, and Meta keeps received media for around 30 days, so download what you want to keep. Deliveries can arrive out of order: when order matters, sort by the top-level sequence.

What has no equivalent, and what to do instead

Keep using the WhatsApp Business app on the phone: Meta disconnects a Coexistence number whose app goes about 14 days without use, and ZapClaw tells your webhook with an account.account_update event (details).

A short adapter

Two functions for Node.js 18 or newer, with no dependency: the first sends where your code called /api/sendText, the second turns a ZapClaw message.received into the payload fields your flow already reads. Check the X-ZapClaw-Signature header before you trust a body.

// 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,
  };
};

The full version is on GitHub: zapclaw/migrate-to-whatsapp-official-api converts text, media, statuses and webhooks and ships a small shim. A call it does not convert, such as a location, a contact card or a reaction, is refused with a clear error code: send those calls straight to ZapClaw's API. Point your flow's WAHA base URL at the shim: it forwards the calls it converts to ZapClaw and turns ZapClaw's signed webhooks back into message, message.any and message.ack events, so you can move first and rewrite later. MIT license.

If your setup is different

What it costs

Meta bills its WhatsApp message fees to you directly, with no ZapClaw markup. Every plan and price.

Related

Sources

Checked on 15 October 2026. WAHA's fields can differ by engine, so check its documentation for the engine you run.

Move your WAHA flows to the official API

Start on the free plan: one number, no card. Move to the Business plan when you need more numbers or more messages.

Start for free Read the webhook docs