grzgrzgrz3/pingwa-client

WhatsApp notifications for AI agents and scripts with **zero setup** — no Meta
account, no templates, no dashboard: text "join", get an API key,
curl → WhatsApp in 60s. Two-way human-in-the-loop: your agent asks, you tap
a button to answer. From your terminal or an MCP client.
This is the **open-source (MIT) pingwa client**: a CLI, a tiny HTTP client, and an
MCP server. It talks to a pingwa backend (the hosted service at
https://pingwa.dev, or your own). The backend is separate and private;
this client is not.
Install & use
No install needed with uv:
**AI agents:** don't ask your human to copy-paste a key — drive the registration
yourself (POST /v1/registrations; full recipe in
llms.txt). The human only taps one WhatsApp link;
the key is claimed by you and never travels through the chat. Works for existing
accounts too — it mints an additional named key.
Exit codes: 0 ok · 2 missing key · 3 quota exceeded · 1 other.
Override the backend with PINGWA_BASE_URL or --base-url.
Webhooks
Prefer PUSH over polling replies? Register HTTPS endpoints and pingwa POSTs
every inbound WhatsApp message to them:
add prints a whsec_... secret **once** — store it now; it never appears
again. Each delivery carries an X-Pingwa-Signature: sha256= header (an
HMAC-SHA256 of the raw body under that secret) — verify it and reject anything
that fails. Full verification recipe and payload shape:
llms.txt. Up to 5 active webhooks per account; to
rotate a secret, rm then add again.
MCP server
Same tools on stdio and remote: notify(text), ask(text, buttons?, timeout?),
check_replies(since?, wait?), check_status(), upgrade().
Local (stdio) — for Claude Desktop / Claude Code:
Remote (Streamable HTTP, no install):
Every error carries an action hint, so an agent knows what to do next.
What it sends
Only your message text and your key, to the pingwa backend you point it at — over
HTTPS. Nothing else. The recipient is always your own phone (there is no "to"
field). See the service's /privacy.