pingwa

pingwa（客户端）

为 AI Agent 和脚本发送 WhatsApp 通知，零配置——无需 Meta 账户、模板或控制面板：发送“join”消息，获取 API 密钥，curl → WhatsApp in 60s。支持双向人工介入：Agent 提问，你点按按钮作答。可通过终端或 MCP 客户端使用。

这是 开源（MIT）的 pingwa 客户端：包含 CLI、轻量 HTTP 客户端和 MCP 服务。它会连接 pingwa 后端（托管服务 https://pingwa.dev 或你自己的后端）。后端是独立的私有服务；此客户端不是。

安装与使用

使用 uv 无需安装：

export PINGWA_KEY=pw_your_key          # get one: send "join" on WhatsApp to the service number
uvx pingwa send "build finished ✅"     # notify your own phone
echo "deploy done" | uvx pingwa send -  # from stdin
uvx pingwa ask "Deploy to prod?" --button yes --button no   # wait for a reply from your phone
uvx pingwa replies                      # pull messages your phone sent back (out-of-band steering)
uvx pingwa me                           # plan / quota / reply-window
uvx pingwa keys                         # list active API keys (up to 10 named keys per number)
uvx pingwa keys revoke ci               # revoke one by name (or reply 'revoke ci' on WhatsApp)
uvx pingwa upgrade                      # get a Stripe link to go Pro (no password needed)
uvx pingwa send "x" --json              # raw JSON response

AI Agent： 不要让用户复制粘贴密钥——自行完成注册（POST /v1/registrations；完整操作流程见 llms.txt）。用户只需点按一个 WhatsApp 链接；密钥由你领取，且不会经过聊天传递。现有账户也可使用——此操作会生成一个额外的命名密钥。

退出码：0 成功 · 2 缺少密钥 · 3 超出配额 · 1 其他错误。 可通过 PINGWA_BASE_URL 或 --base-url 更改后端地址。

Webhook

相比轮询 replies，更喜欢 PUSH？注册 HTTPS 端点后，pingwa 会将每条收到的 WhatsApp 消息 POST 到这些端点：

uvx pingwa webhooks                                   # list your webhooks
uvx pingwa webhooks add https://your-host/pingwa-hook # returns a signing SECRET, shown ONCE
uvx pingwa webhooks rm https://your-host/pingwa-hook  # by id, or by exact url

add 只会显示一次 whsec_... 密钥 ——请立即保存；之后不会再次显示。每次投递都会携带 X-Pingwa-Signature: sha256=<hex> 标头（使用该密钥对原始请求体计算的 HMAC-SHA256），请验证签名并拒绝所有验证失败的请求。完整的验证流程和负载格式见： llms.txt。每个账户最多可启用 5 个 Webhook；如需轮换密钥，请先运行 rm，再运行 add。

MCP 服务

stdio 和远程服务提供相同的工具：notify(text)、ask(text, buttons?, timeout?)、 check_replies(since?, wait?)、check_status()、upgrade()。

本地（stdio）——适用于 Claude Desktop / Claude Code：

{
  "mcpServers": {
    "pingwa": {
      "command": "uvx",
      "args": ["pingwa", "mcp"],
      "env": { "PINGWA_KEY": "pw_your_key" }
    }
  }
}

远程（Streamable HTTP，无需安装）：

{
  "mcpServers": {
    "pingwa": {
      "url": "https://pingwa.dev/mcp",
      "headers": { "Authorization": "Bearer pw_your_key" }
    }
  }
}

每条错误都会附带 action 提示，让 Agent 知道接下来该做什么。

发送内容

只会通过 HTTPS 将你的消息文本和密钥发送到你指定的 pingwa 后端。不会发送其他内容。接收方始终是你自己的手机（没有“to”字段）。请参阅该服务的 /privacy。

许可证

MIT——请参阅仓库根目录中的 LICENSE。该许可证仅适用于此客户端包（src/pingwa/client/）；pingwa 服务端是独立的私有项目，未公开发布。确切的适用范围见 NOTICE。