agent-whatsapp

Agent WhatsApp

AI エージェント向けの、Baileys を利用した WhatsApp CLI です。QR コードまたはペアリングコードを使ってコンパニオンデバイスとしてリンクするため、スマートフォンの接続は維持されます。各コマンドの実行時に接続し、完了後に切断します。

次のいずれかのエントリーポイントを使用します。

• グローバルインストール：agent-whatsapp ...
• 一時実行：bunx --package agent-messenger agent-whatsapp ...

主な概念

始める前に、WhatsApp のアーキテクチャについていくつか説明します。

• JID（Jabber ID）＝WhatsApp のアドレス形式です。個人の場合：[email protected]。グループの場合：[email protected]。通常の電話番号を渡すこともでき、CLI が自動的に JID に解決します。
• QR コード認証＝ターミナルまたはブラウザーに表示される QR コードをスキャンして、CLI をコンパニオンデバイスとしてリンクします。WhatsApp を開き、［リンク済みデバイス］>［デバイスをリンク］を選択して、コードをスキャンしてください。
• ペアリングコード認証＝ターミナルに表示される数字コードを使って、CLI をコンパニオンデバイスとしてリンクします。スマートフォンの WhatsApp で［リンク済みデバイス］を開き、コードを入力してください。
• オンデマンド接続＝CLI はコマンドごとに WebSocket 接続を開き、コマンドの実行後に切断します。バックグラウンドで常時実行されるプロセスはありません。
• 複数アカウント＝複数の WhatsApp アカウントをリンクできます。auth list と auth use を使って切り替えます。

クイックスタート

# Link as companion device via QR code (scan with your phone)
agent-whatsapp auth login --qr

# Or link via pairing code (enter the code on your phone)
agent-whatsapp auth login --phone +1234567890

# List chats
agent-whatsapp chat list

# Send a message
agent-whatsapp message send +1234567890 "Hello from agent-whatsapp"

認証の流れ

WhatsApp は 2 種類の認証方法に対応しています。どちらも CLI をコンパニオン（リンク済み）デバイスとして登録するため、スマートフォンのセッションには影響しません。

• QR コード（--qr）：ターミナルに QR コードが表示され、ブラウザーで開かれます。スマートフォンの WhatsApp でスキャンしてください。電話番号は不要です。
• ペアリングコード（--phone）：数字コードが表示されます。スマートフォンの WhatsApp で［リンク済みデバイス］>［電話番号でリンク］を開き、コードを入力してください。

エージェントの動作（必須）

アカウントが設定されていないためにコマンドが失敗した場合、エージェントは認証フローを自ら進めなければなりません。ユーザーにコマンドの実行を指示してはいけません。すべてエージェントが実行します。

ステップ 1：既存のアカウントを確認する

agent-whatsapp auth list

アカウントが存在する場合は、agent-whatsapp auth use <account-id> を使ってから、元のコマンドを再試行します。

ステップ 2：アカウントがない場合は QR ログインを開始する（推奨）

agent-whatsapp auth login --qr
# -> QR code displayed in terminal + opened in browser
# -> {"next_action":"scan_qr","qr_url":"...","message":"Scan with WhatsApp on your phone"}

ユーザーに WhatsApp で QR コードをスキャンするよう伝えてください。操作手順は、［設定］>［リンク済みデバイス］>［デバイスをリンク］> QR コードをスキャン、です。

代替方法：ペアリングコードでログインする

QR コードをスキャンできない場合（ヘッドレス環境など）は、電話番号を尋ね、ペアリングコードを使います。

agent-whatsapp auth login --phone +1234567890
# -> {"pairing_code":"A1B2-C3D4","message":"Enter this code in WhatsApp > Linked Devices > Link with phone number"}

ユーザーにペアリングコードを伝え、スマートフォンで入力するよう依頼してください。

ステップ 3：確認を待つ

CLI は、ユーザーがスマートフォンで確認するまで待機します。確認されたら、次の操作を行います。

# -> {"authenticated":true,...}

ステップ 4：元のコマンドを再試行する

認証に成功したら、ユーザーが最初に依頼した操作をすぐに実行します。

よく使う認証コマンド

agent-whatsapp auth status              # Check current auth state
agent-whatsapp auth status --account <id>  # Check specific account
agent-whatsapp auth list                # List all linked accounts
agent-whatsapp auth use <id>            # Switch active account
agent-whatsapp auth logout              # Unlink current account
agent-whatsapp auth logout --account <id>  # Unlink specific account

メモリ

エージェントは、セッションをまたいで情報を保持するため、~/.config/agent-messenger/MEMORY.md ファイルを維持します。このファイルはエージェントが管理します。CLI はこのファイルの読み取りも書き込みも行いません。メモリファイルの管理には Read ツールと Write ツールを使用してください。

メモリの読み取り

すべてのタスクの開始時に、Read ツールを使って ~/.config/agent-messenger/MEMORY.md を読み込み、これまでに見つかったチャット ID、連絡先の名前、設定を確認してください。

• ファイルがまだ存在しない場合は問題ありません。ファイルなしで作業を進め、保存する有用な情報が初めて見つかった時点で作成してください。
• ファイルを読み取れない場合（権限がない、ディレクトリがないなど）は、メモリなしで作業を進めてください。

メモリの書き込み

有用な情報を見つけたら、Write ツールを使って ~/.config/agent-messenger/MEMORY.md を更新してください。次のような場合は書き込みを行います。

• チャット JID と連絡先名を見つけた後（chat list から）
• グループ名と参加者を見つけた後
• ユーザーから別名や設定を伝えられた後（「これを家族グループと呼んで」「仕事のチャットは X」など）

書き込む際は、ファイルの内容全体を含めてください。Write ツールはファイル全体を上書きします。

保存する情報

• 連絡先名／グループ名を含むチャット JID
• 自分の電話番号と JID
• ユーザーが指定した別名（「家族グループ」「仕事のチャット」など）
• よく参照するチャット JID
• やり取り中に示されたユーザーの好み

保存しない情報

認証情報、セッションキー、その他の機密情報は絶対に保存しないでください。メッセージの全文は保存せず、ID とチャットのコンテキストのみを保存してください。

古いデータの扱い

記憶した JID でエラーが返された場合は、MEMORY.md から削除してください。記憶したデータを盲目的に信頼しないでください。古くなっている可能性のある JID を使うより、再度一覧を取得してください。

形式／例

# Agent Messenger Memory

## WhatsApp Account

- Phone: +1234567890
- JID: [email protected]

## Chats

- `[email protected]` - Alice (1:1)
- `[email protected]` - Bob (1:1)
- `[email protected]` - Project Team (group, 8 members)
- `[email protected]` - Family (group, 5 members)

## Aliases

- "alice" -> `[email protected]`
- "project" -> `[email protected]` (Project Team)
- "family" -> `[email protected]` (Family group)

## Notes

- User prefers --pretty output
- Project Team is the most frequently used chat

メモリーを使うと、chat list の呼び出しを繰り返さずに済みます。前のセッションですでに把握している JID がある場合は、そのまま使用してください。

コマンド

認証コマンド

# Link as companion device via QR code (no phone number needed)
agent-whatsapp auth login --qr

# Link as companion device via pairing code
agent-whatsapp auth login --phone +1234567890

# Check auth status
agent-whatsapp auth status
agent-whatsapp auth status --account <id>

# List linked accounts
agent-whatsapp auth list

# Switch active account
agent-whatsapp auth use <id>

# Unlink account
agent-whatsapp auth logout
agent-whatsapp auth logout --account <id>

Whoami コマンド

# Show current authenticated user
agent-whatsapp whoami
agent-whatsapp whoami --pretty
agent-whatsapp whoami --account <account-id>

出力には、認証済みユーザーの ID 情報が含まれます。

チャットコマンド

# List chats (sorted by most recent activity)
agent-whatsapp chat list
agent-whatsapp chat list --limit 50
agent-whatsapp chat list --account <id>

# Search chats by name
agent-whatsapp chat search "project"
agent-whatsapp chat search "project" --limit 10
agent-whatsapp chat search "project" --account <id>

出力には次の情報が含まれます。

• jid - チャット JID（個人またはグループ）
• name - 連絡先名またはグループ名
• unread_count - 未読メッセージ数
• last_message - 最新メッセージのプレビュー

メッセージコマンド

# List messages in a chat
agent-whatsapp message list <chat> --limit 20
agent-whatsapp message list +1234567890 --limit 50
agent-whatsapp message list [email protected] --limit 10
agent-whatsapp message list +1234567890 --limit 20 --account <id>

# Send a text message
agent-whatsapp message send <chat> <text>
agent-whatsapp message send +1234567890 "Hello!"
agent-whatsapp message send [email protected] "Hello team!"
agent-whatsapp message send +1234567890 "Hello!" --account <id>

# Edit one of your own messages (within ~15 minutes)
agent-whatsapp message edit <chat> <message-id> <text>
agent-whatsapp message edit +1234567890 ABC123DEF456 "Updated text"

# React to a message
agent-whatsapp message react <chat> <message-id> <emoji>
agent-whatsapp message react +1234567890 ABC123DEF456 "👍"
agent-whatsapp message react +1234567890 ABC123DEF456 "👍" --from-me
agent-whatsapp message react +1234567890 ABC123DEF456 "👍" --account <id>

<chat> 引数には次の値を指定できます。

• 電話番号：+1234567890（JID に自動解決されます）
• 個人 JID：[email protected]
• グループ JID：[email protected]

message react の --from-me フラグは、対象のメッセージが自分から送信された（送信メッセージである）ことを示します。このフラグを指定しない場合、リアクションの対象は受信メッセージになります。

出力形式

JSON（デフォルト）

すべてのコマンドは、AI が利用しやすいよう、デフォルトで JSON を出力します。

{
  "jid": "[email protected]",
  "name": "Alice",
  "unread_count": 3,
  "last_message": {
    "id": "ABC123DEF456",
    "text": "See you tomorrow!",
    "from": "[email protected]",
    "timestamp": 1705312200
  }
}

Pretty（人間が読みやすい形式）

整形された出力には --pretty フラグを使用してください。

agent-whatsapp chat list --pretty

グローバルオプション

オプション	説明
--pretty	JSON の代わりに人間が読みやすい形式で出力します
--account <id>	このコマンドで特定のアカウントを使用します

よく使うパターン

未読メッセージを確認する

# List chats to see unread counts
agent-whatsapp chat list --limit 20

# Read messages from a specific chat
agent-whatsapp message list +1234567890 --limit 10

連絡先にメッセージを送信する

# By phone number (simplest)
agent-whatsapp message send +1234567890 "Hey, are we still on for tomorrow?"

# By JID
agent-whatsapp message send [email protected] "Hey, are we still on for tomorrow?"

グループにメッセージを送信する

# Find the group first
agent-whatsapp chat search "Project Team"

# Send to the group JID
agent-whatsapp message send [email protected] "Status update: deployment complete."

最新のメッセージにリアクションする

# Get the latest message ID
agent-whatsapp message list +1234567890 --limit 1

# React to it
agent-whatsapp message react +1234567890 <message-id> "👍"

自分が送信したメッセージを編集する

# Get the message ID of a message you sent
agent-whatsapp message list +1234567890 --limit 5

# Edit it (only your own messages, within ~15 minutes)
agent-whatsapp message edit +1234567890 <message-id> "Updated text"

SDK では、WhatsAppClient.editMessage を使って同じ機能を利用できます。

import { WhatsAppClient } from 'agent-messenger/whatsapp'

const client = await new WhatsAppClient().login()
const sent = await client.sendMessage('+1234567890', 'Deploying…')
await client.editMessage('+1234567890', sent.id, 'Deployed ✅')

エラー処理

すべてのコマンドは、一貫した形式でエラーを返します。

{
  "error": "No WhatsApp account linked. Run: agent-whatsapp auth login --qr"
}

よくあるエラー：

• No WhatsApp account linked - 認証されていません。auth login --qr または auth login --phone <number> を実行してください。
• Connection timeout - WhatsApp への WebSocket 接続に失敗しました。コマンドを再試行してください。
• Invalid JID - 電話番号または JID の形式が正しくありません。+ を先頭に付けた国際形式を使用してください。
• Not a group participant - メンバーになっていないグループには送信できません。

注意事項

• JID の形式：個人チャットでは [email protected]、グループでは [email protected] を使用します。電話番号を直接渡すこともでき、その場合は JID に自動解決されます。
• 必要時に接続：各コマンドは WebSocket 接続を開き、処理が完了すると閉じます。常駐デーモンやバックグラウンドプロセスはありません。
• アカウント停止のリスク：WhatsApp は自動化された動作を監視しています。大量のメッセージ送信、短時間での連続送信、一括操作は避けてください。複数のメッセージを送信する場合は、コマンドの実行間隔を空けてください。
• 複数アカウント：複数の WhatsApp 番号を同時にリンクできます。auth list ですべてのアカウントを確認し、auth use <id> で切り替えてください。
• 電話番号：国番号を含む国際形式を必ず使用してください（例：+1234567890、+821012345678）。
• agent-whatsapp はデフォルトで JSON を返し、インデント付きの出力には --pretty を使用します。

トラブルシューティング

agent-whatsapp: command not found

agent-whatsapp は npm パッケージ名ではありません。 npm パッケージ名は agent-messenger です。

パッケージがグローバルにインストールされている場合は、agent-whatsapp を直接使用してください。

agent-whatsapp chat list --pretty

パッケージがインストールされていない場合は、--package を使ってインストールして実行してください。

npx -y --package agent-messenger agent-whatsapp chat list --pretty
bunx --package agent-messenger agent-whatsapp chat list --pretty
pnpm dlx --package agent-messenger agent-whatsapp chat list --pretty

--package agent-messenger を指定せずに、npx agent-whatsapp、bunx agent-whatsapp、または pnpm dlx agent-whatsapp を実行しないでください。 agent-whatsapp は npm パッケージ名ではないため、実行に失敗するか、誤ったパッケージがインストールされます。

QR コードをスキャンできない

1. スマートフォンで WhatsApp が開いていることを確認してください
2. 「設定」>「リンク済みデバイス」>「デバイスをリンク」に移動してください
3. スマートフォンのカメラを、ターミナルまたはブラウザーに表示された QR コードに向けてください
4. QR コードの有効期限が切れた場合は、auth login --qr を再度実行して新しいコードを取得してください
5. QR コードをスキャンできない場合は、ペアリングコードを試してください：auth login --phone <number>

ペアリングコードが機能しない

1. スマートフォンで WhatsApp が開いていることを確認してください
2. 「設定」>「リンク済みデバイス」>「デバイスをリンク」に移動してください
3. QR コードが表示されている場合は、「電話番号でリンク」を選択してください
4. ターミナルに表示されたペアリングコードを入力してください
5. コードの有効期限が切れた場合は、auth login --phone <number> を再度実行して新しいコードを取得してください

新しいデバイスをリンクした後にチャットリストが空になる

WhatsApp のコンパニオンデバイスは、チャットリストをメインのスマートフォンから受け取ります。直接取得できるサーバー API はありません。新しくリンクしたデバイスでは、個人チャット／DM の場合、chat list を実行してもグループチャットしか（または何も）表示されないことがあります。

• リンク中およびリンク後は、WhatsApp を開いたままスマートフォンをオンラインにしておいてください。 スマートフォンから新しいデバイスに履歴が送信されます。スマートフォンの電源が切れているか、WhatsApp が強制終了されていると、何も届きません。
• 数分待ってから、chat list を再度実行してください。履歴は時間をかけて少しずつ同期され、ローカルに保存されるため、以降の実行では表示されるチャットが増えます。
• グループは常にすぐに利用できます。 履歴の同期ではなく、サーバーから取得されるためです。
• 既知の電話番号にメッセージを送信すると、初回の同期に含まれていなくても、そのチャットが表示されるようになります。

これは WhatsApp プロトコルの制限であり、バグではありません。

接続が切断される

WhatsApp は、長期間使用されていないリンク済みデバイスを切断することがあります。コマンドが失敗し始めた場合は、次の操作を行ってください。

# Check if still linked
agent-whatsapp auth status

# Re-link if needed
agent-whatsapp auth login --qr