WhatsApp

Meta の Cloud API 経由でアウトバウンドメッセージを送信します。ビジネスアカウントが必要で、セッションウィンドウの制限があり、送信専用です。

🟢 ランタイム対応済み SDK を使わず Meta Cloud API v21 を直接呼び出します。ストリーミング編集には非対応です。Cloud API の編集ウィンドウはわずか 15 分で、レート制限も厳しいため実装コストに見合いません。ヘルパーは token をバッファリングし、finalize 時に一括送信します。

利用できる機能

確認済みの Meta ビジネス番号から、任意の WhatsApp 番号（E.164 形式）へメッセージを送信
channel による1メッセージ単位の宛先オーバーライド
メッセージあたり最大 4,096 文字（ヘルパーのデフォルトと同じ）

事前に必要なもの

WhatsApp は手軽にセットアップできるプロバイダーではありません。以下が必要です。

Meta Business Portfolio（business.facebook.com）
そのポートフォリオに紐づいた WhatsApp Business 電話番号（SMS または音声で確認できる番号）
WhatsApp 製品を追加済みの Meta Developer App（developers.facebook.com）
テスト番号以外への本番メッセージ送信：Meta Business Suite でビジネス認証を完了（数時間〜数日かかります）

まず試してみたい場合は、Developer App に無料テスト受信者番号が5件付属しており、アプリの WhatsApp パネルで SMS 認証できます。

セットアップ

1. アクセストークンの取得

developers.facebook.com → 対象アプリ → WhatsApp → API Setup
初期テスト用の Temporary access token（24 時間有効）をコピーするか、長期利用向けに System User access token を発行します。手順：business.facebook.com → Settings → Users → System Users → ユーザーを作成 → Generate new token（スコープ：whatsapp_business_messaging と whatsapp_business_management）

2. 電話番号 ID と宛先の取得

同じ API Setup ページの From ドロップダウンにビジネス電話番号が表示されます。その下にある数値の Phone number ID が Minara に必要なものです（+... 形式の番号自体ではありません）
To の欄で SMS 認証を行い、宛先を追加します。E.164 形式の番号（例：+12025551234）を WHATSAPP_RECIPIENT に設定してください

3. Minara の設定

minara auth messaging add whatsapp

またはプロジェクトルートの .env ファイルに直接記述します。

WHATSAPP_ACCESS_TOKEN=EAAxxx...
WHATSAPP_PHONE_NUMBER_ID=1234567890
WHATSAPP_RECIPIENT=+12025551234

4. テスト

minara auth messaging test whatsapp

24 時間セッションウィンドウ

これは誰もが一度は引っかかる落とし穴です。

Meta では、ユーザーが最後に受信メッセージを送ってから 24 時間以内のみ、ビジネス側から自由形式のメッセージを無料で送信できます。ウィンドウを過ぎると、事前承認済みのテンプレートメッセージを使う必要があります。

アクティブな会話中のエージェントアラートには問題ありませんが、一方的な通知（例：夜間の Autopilot 取引）には不便です。対処方法は以下のとおりです。

ユーザーがビジネス番号にメッセージを送信する。ユーザーからのメッセージで 24 時間ウィンドウがリセットされます
承認済みテンプレートを使用する。{{1}} ({{2}}) triggered at {{3}} のようなアラートテンプレートを Meta Business Suite に登録します。テンプレート送信にはウィンドウ制限がありません（テンプレートごとのレート制限は別途適用されます）
別のプロバイダーを使う。一方的なアラートにはメール、Telegram、Signal が適しています

Minara は現在プレーンテキストのみ送信対応です。テンプレートのサポートは今後追加予定です。

宛先のオーバーライド

send_message({
  provider: "whatsapp",
  channel: "+12025559999",
  text: "Critical: position liquidation imminent",
})

オーバーライド先の番号は、テスト番号の場合は Meta Developer App で認証済みである必要があります。本番環境の場合は、確認済みのビジネス送信者から到達できる番号が必要です。

トラブルシューティング

「Recipient not in allowed list」

テストティアを使用しており、オーバーライド先の番号が5件の確認済みテスト番号に含まれていません。Developer App の WhatsApp パネルで追加してください

「Token expired」

一時トークンは 24 時間で失効します。本番環境に近い用途では System User トークンに切り替えてください

「Message failed. outside 24h window」

上記のセッションウィンドウのセクションを参照してください。ユーザーにビジネス番号へメッセージを送ってもらいウィンドウを再開するか、一方的な送信にはテンプレートを登録してください

「Rate limit exceeded」

新規アカウントはビジネス発信の会話が1日あたり約 50 件に制限されています。ビジネス認証ティアに応じてスケールします。詳細は Meta のスケーリングに関するドキュメントを参照してください

リファレンス

環境変数：WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_RECIPIENT
ソース：apps/agent/src/messaging/whatsapp.ts
Cloud API ドキュメント：developers.facebook.com/docs/whatsapp/cloud-api

目次