mcpField
W
whatsapp

whatsapp

github.com/sanjay3290生産性44878 回インストール7 週間前に更新
リポジトリ

whatsapp について

whatsapp（pywhats）は、非公式のクライアントとして、非同期 Python と CLI から WhatsApp のリンク済み端末を操作します。テキストと画像の送信、イベント監視、複数アカウントのセッションに対応します。

主な機能

  1. 01QR コードでのペアリングとセッション再開
  2. 021 対 1 のテキスト・画像送信
  3. 03グループへのテキスト送信と情報取得
  4. 04JSON イベントストリームの監視
  5. 05プレゼンス、既読、入力状態の管理

活用シーン

  1. 01スクリプトから個別チャットへテキストや画像を送信
  2. 02グループへのメッセージ送信と情報取得
  3. 03チャットイベントを監視して受信メッセージを処理
  4. 04複数の WhatsApp アカウント間でセッションを切り替え

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/sanjay3290/ai-skills --skill whatsapp

インストール後、Claude Code で/whatsappを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
references/
api.md
scripts/
_bootstrap.sh
wa.py

詳細

WhatsApp（pywhats）

pywhats を使い、非同期 Python から WhatsApp アカウントをリンク済みコンパニオンデバイス（WhatsApp Web のようなもの）として操作します（プレアルファ版、テキスト／画像のみ）。これは非公式のマルチデバイスクライアントであり、公式の WhatsApp Business／Cloud API ではありません。

CLI のエントリーポイント：scripts/wa.py（初回実行時に管理対象の venv を自動でセットアップします）。

基本的な仕組み

  • ペアリング＝QR コードの初回スキャンです。 wa.py pair を実行すると ASCII QR コードが表示されます。WhatsApp → リンク済みデバイスからスキャンしてください。認証情報は $PYWHATS_HOME/<session>.session（および .signal.db）に保存されます。
  • 再接続はサイレントです。 以降のコマンドは同じセッションで再接続するため、QR コードは不要です。
  • チャットの宛先には JID を使います。 電話番号のみの 15550001234 は [email protected] に変換されます。グループには [email protected] を使います。
  • 受信にはイベントを使います。 wa.py listen はイベントごとに JSON オブジェクトを 1 つ出力します。

⚠️ ハンドラー内で Client 呼び出しを直接 await しないでください

イベントハンドラーは受信ループ内でインライン実行されます。ハンドラー内で send_*、mark_read、get_group_info、download_media などを await すると、接続がデッドロックします。必ず asyncio.create_task(...) を使ってください。listen サブコマンドは --read に対してすでにこの方法を使っています。

コマンド

scripts/wa.py pair                                          # one-time QR pair
scripts/wa.py send-text 15550001234 "hello"                 # 1:1 text
scripts/wa.py send-image 15550001234 photo.jpg --caption hi # 1:1 image
scripts/wa.py group-info [email protected]            # group metadata JSON
scripts/wa.py group-send [email protected] "hi all"   # group text
scripts/wa.py mark-read 15550001234 MSGID [--sender JID]    # blue ticks
scripts/wa.py presence available                            # global presence
scripts/wa.py typing 15550001234 composing [--media audio]  # typing indicator
scripts/wa.py listen --read --events message,receipt        # JSONL event stream
scripts/wa.py --session work send-text 15550001234 "hi"     # named session
コマンド動作
pairASCII QR コードで新規リンクします。ペアリング済みの場合は何もしません
send-text <to> <text>1 対 1 のテキストを送信し、メッセージ ID を出力します
send-image <to> <path> [--caption C]画像（jpg/png/webp、≤16MB）を送信し、ID を出力します
group-info <gid>グループの JSON（件名、所有者、参加者など）を出力します
group-send <gid> <text>メンバーを解決してからグループにテキストを送信し、ID を出力します
mark-read <chat> <ids...>既読にします。グループでは --sender を指定します
presence <available|unavailable>全体のプレゼンス
typing <to> <composing|paused>チャットのプレゼンス。--media audio は任意です
listenJSON Lines を継続的に出力します。--read、--events、--subscribe JID を指定できます（プレゼンスイベントには必須）

グローバルオプション：--session NAME（デフォルトは default。環境変数 PYWHATS_SESSION でも指定できます） — サブコマンドの前に指定します：wa.py --session work pair。

セッション／複数アカウント

$PYWHATS_HOME/                 # default: ~/.pywhats
  venv/                        # managed Python + pywhats
  default.session              # --session default
  default.session.signal.db
  work.session                 # --session work

PYWHATS_HOME でホームディレクトリを変更できます。ペアリングされていないセッション、またはログアウト済みのセッションでは、wa.py --session <name> pair を再実行するよう明確なメッセージが表示されます。

スキャン直後にデバイスがログアウトしたと pair が報告した場合は、WhatsApp によるデバイス整理の結果であり、スキルの不具合ではありません。無効になったセッションは自動的に削除されます。表示される復旧手順（リンク済みデバイスを削除し、15～20 分待ってから、1 回だけペアリングする）に従ってください。

詳細リファレンス

references/api.md — すべての Client メソッド、すべてのイベントペイロード、JID の構築方法、および download_media に関する注意事項。

コメント

Markdown 対応