pingwa

pingwa（クライアント）

AI エージェントやスクリプト向けの WhatsApp 通知を設定不要で利用できます。Meta アカウントも、テンプレートも、ダッシュボードも不要です。「join」とテキストを送信して API キーを取得し、 curl → WhatsApp in 60s。人間が介在する双方向のやり取りにも対応しています。エージェントが質問し、あなたはボタンをタップして回答します。ターミナルまたは 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 エージェント：**人間にキーのコピー＆ペーストを頼まず、自分で登録を進めてください（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 を参照してください。アカウントごとに有効な Webhook は最大 5 つです。シークレットをローテーションするには、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 のヒントが含まれているため、エージェントは次に何をすべきか判断できます。

送信されるデータ

指定した pingwa バックエンドに、メッセージのテキストとキーだけを HTTPS 経由で送信します。それ以外は送信しません。宛先は常にあなた自身の電話番号です（「to」フィールドはありません）。サービスの /privacy を参照してください。

ライセンス

MIT — リポジトリのルートにある LICENSE を参照してください。これはこのクライアントパッケージ（src/pingwa/client/）のみを対象とします。pingwa サーバーは別個の非公開プロジェクトであり、公開されていません。正確な範囲については NOTICE を参照してください。