wapit documentation

wapit is a local WhatsApp Cloud API for development: Mailpit, but for WhatsApp. Point your app's Graph API base URL at wapit, keep your real code paths, and see each message in a local inbox that looks like a chat. It is not affiliated with Meta or WhatsApp.

With Homebrew on macOS or Linux:

$ brew install patriciomartinns/tap/wapit

Or run the container. The last two options let wapit deliver webhooks to apps on your machine, such as http://localhost:8000, from inside the container:

$ docker run --rm -p 127.0.0.1:8026:8026 -p 127.0.0.1:8027:8027 \
  --add-host host.docker.internal:host-gateway \
  -e WAPIT_LOOPBACK_HOST=host.docker.internal \
  ghcr.io/patriciomartinns/wapit

Or build from source with Rust 1.89 or newer:

$ cargo install --locked --git https://github.com/patriciomartinns/wapit

On Windows, download wapit-<version>-x86_64-pc-windows-msvc.zip from the latest release, unzip it and run wapit.exe. The same page has prebuilt binaries for macOS and Linux, and a SHA256SUMS file to check them: github.com/patriciomartinns/wapit/releases/latest

Run wapit with no configuration and it serves one default app. The inbox is on http://127.0.0.1:8026 and the Graph API on http://127.0.0.1:8027.

Set the same values in your app, with http://127.0.0.1:8027 as the Graph API base URL, and send a message:

$ curl http://127.0.0.1:8027/v26.0/100000000000001/messages \
  -H 'Authorization: Bearer wapit-local-token' \
  -H 'Content-Type: application/json' \
  -d '{"messaging_product":"whatsapp","to":"15550000000","type":"text","text":{"body":"Hello"}}'

A free-form message to someone who never wrote to you is accepted and then fails with error 131047, exactly as Meta does outside the 24-hour service window. Reply as the user from the inbox to open the window.

wapit accepts any version in the path, or none. The examples use v26.0, the latest stable Graph API version, and webhooks have the v24.0 and later shape, without the conversation object in statuses.

Copy config/apps.example.json to config/apps.json to describe your own apps. Each app is one WhatsApp phone number:

The file reloads when it changes. If an edit breaks it, wapit keeps the last good version and shows the error in the inbox.

Templates live in config/templates/<app id>.json, in the format Meta's message_templates endpoint returns. Your app can also create, edit and delete them through the Graph API, and they are approved right away.

Copy them from your real account, read-only, with:

$ WAPIT_SYNC_TOKEN=... wapit sync <app id>

It reads Graph API v26.0 unless the app's sync.graph_version says otherwise. Synced templates keep Meta's ids, so POST /{template_id} and hsm_id use the same ids as your real account. This is the only command that talks to Meta, and only when you run it.

An app running in another container must reach wapit by a name that resolves there, such as host.docker.internal:8027. Media URLs follow WAPIT_PUBLIC_API_URL, so set it to that same address.

A reaction gets only the sent status, as on Meta, and a reaction to a message that is not in the chat, is itself a reaction or is more than 30 days old is accepted and then fails with error 131009.

Send with recipient set to a business-scoped user ID (BSUID), such as US.13491208655302741918, instead of to, and the response names the contact as user_id instead of wa_id. When a send has both, to wins, as on Meta. Webhooks have the shape Meta has used since April 2026: contacts[].user_id, messages[].from_user_id and statuses[].recipient_user_id are always there, and wa_id, from and recipient_id only in phone number conversations. wapit derives a stable BSUID for each phone number from the number and the WhatsApp Business Account id. A send whose recipient is that derived BSUID goes to the phone number's conversation, inside its service window. One-tap, zero-tap and copy code authentication templates cannot be sent to a BSUID (131062). Group recipients (recipient_type: group) are not supported.

Sends are checked like Meta checks them. A rejected send returns Meta's error to your app and stays in the inbox, flagged, with the reason in plain words.

In a conversation you can type a message, attach a file, tap a reply, quick reply or list button, or select one of your app's messages to mark it delivered, read, played (voice messages only) or failed with a real Meta error code. Every action is posted to the app's webhook in Meta's payload format, signed with the app secret in X-Hub-Signature-256. As on Meta, the pricing object comes with the sent status and with the first of delivered or read, never with both.

The inspector shows the payload your app sent, each webhook delivery with your app's response, and lets you send a webhook again. Apps with a verify_token can also run the subscription handshake from the inbox.

wapit delivers each webhook once. Unlike Meta, which retries a failed delivery, it does not retry on its own: if your app is down or answers with an error, the delivery is marked failed in the inspector and you send it again from there.

wapit has no authentication by design: it is a development tool for your own machine.

• It binds to 127.0.0.1.
• It only answers requests whose Host is a local name, so a web page cannot reach it through DNS rebinding.
• Its Graph API refuses writes that carry a browser's Origin, so a page you visit cannot send messages through it with the default token.

Do not publish its ports beyond your machine. Report vulnerabilities privately through GitHub: github.com/patriciomartinns/wapit/security