前提条件
接続を作成する前に、Metaから以下を入手する必要があります。| 要件 | 入手先 |
|---|---|
| WhatsApp Business Account（認証済み） | Meta Business Manager |
| System User Access Token | Meta Business Manager → System Users |
| Phone Number ID | WhatsApp Manager → Phone Numbers |
| Business Account ID | オプション — 高度なGraph API呼び出しに必要 |
| 承認済みメッセージテンプレート | Meta Business Manager → Account Tools → Message Templates |
接続の作成
WhatsApp ツールキットはAgent BuilderとWorkflow Builderの両方で利用可能です。接続のセットアップは両方で同じですが、ナビゲーションパスが異なります。- Agent Toolkit
- Workflow Toolkit
- Agent Builderでエージェントを開きます
- 左サイドバーのToolkitsタブに移動します
- WhatsAppを見つけてAdd to Agentをクリックします
- ツールキットパネルで、Select a Connection > Create a Connectionをクリックします
- 表示されるポップアップで、Connection Name、System User Access Token、Business Account IDを入力します
- Access Token、Business Account ID（オプション）、接続の表示用Nameを入力します
- Saveをクリックします — EKBは保存前に認証情報を検証します
利用可能なツール
| ツール | 説明 |
|---|---|
| Send Message | 24時間セッションウィンドウ内でプレーンテキストメッセージ（最大4,096文字、UTF-8）を送信します |
| Send Media | パブリックHTTPS URL経由で画像、動画、音声、ドキュメントを送信します。オプションのキャプションまたはファイル名を付与できます |
| Send Template | 承認済みテンプレートメッセージを送信します — 24時間セッションウィンドウ外の送信メッセージに必要です |
| Custom API Call | 高度なユースケースのために、任意のMeta Graph APIエンドポイントへの直接呼び出しが可能です（以下参照） |
Custom API Call
Custom API Callツールは最も拡張性の高いオプションです。他のツールがカバーする範囲を超えて、WhatsApp Graph APIエンドポイントに直接アクセスできます。以下が含まれます。- インタラクティブメッセージ（ボタン、リスト）
- 位置情報および連絡先カード
- 商品カタログメッセージ
- プログラマティックテンプレート管理
- ビジネスプロフィールの更新
- メッセージング分析とインサイト
設定に関する注意事項
- 電話番号形式: 常にE.164国際形式を使用してください（例：
+1...、+52...）。スペース、ハイフン、国コードの欠落は配信エラー（エラー1006）の原因となります。 - セッションウィンドウ: プレーンテキストとメディアメッセージは、受信者の最後のメッセージから24時間以内にのみ送信可能です。その期間を過ぎた場合は、代わりにSend Templateを使用してください。
- メディアURL: HTTPS経由で公開アクセス可能でなければなりません。プライベート、ローカルホスト、または期限切れのURLはダウンロードエラー（エラー
1011）の原因となります。MIMEタイプがファイルコンテンツと一致することを確認してください。 - テンプレート: 使用前にMeta Business Managerで承認が必要です。パラメータの数と順序は承認済みテンプレートと完全に一致させる必要があります。テンプレートの品質評価を監視してください。低評価はテンプレートの一時停止（エラー
131056）につながる可能性があります。 - レート制限: WhatsApp Business APIは番号別・日別メッセージング制限を適用しています。一括送信の場合は、キューを使用し、指数バックオフによるリトライロジックを実装してください。
- セキュリティ: アクセストークンを安全に保管し、定期的に資格情報を更新してください。マーケティングメッセージを送信する前にユーザーの同意を取得してください。
実践的な例
- カスタマーサポート: エージェントがサポートリクエストを受信し、顧客レコードを参照し、チケット番号と次のステップを含むWhatsAppメッセージを送信します — またはインタラクティブボタンテンプレートを使用して適切なチームにユーザーをルーティングします。
- トランザクション通知: ワークフローが注文後にトリガーされ、注文確認、配送更新、支払い通知のテンプレートを送信します。
- ドキュメント配信: エージェントがPDF請求書や契約書を生成し、説明付きキャプションでSend Mediaツールを介して配信します。
- ブロードキャストキャンペーン: ワークフローが連絡先リストを反復処理し、パーソナライズされたパラメータ置換付きの承認済みマーケティングテンプレートを送信します。
トラブルシューティング
| エラーコード | 症状 | 対処 |
|---|---|---|
401 / 190 | 無効なアクセストークン | Meta Business ManagerでSystem Userトークンを再生成し、接続を更新 |
33 | 無効なPhone Number ID | WhatsApp ManagerでPhone Number IDを確認 |
1006 | 無効な電話番号形式 | E.164形式を使用 — +と国コードを含め、スペースやハイフンは使用しない |
131005 | テンプレートが見つからない | テンプレート名とMeta Business Managerに存在することを確認 |
131056 | テンプレートが一時停止 | Meta Business Managerでテンプレートの品質評価を確認 |
1011 | メディアダウンロード失敗 | パブリックHTTPS URLを使用し、ファイルタイプとMIMEタイプがサポートされていることを確認 |
- 認証情報と接続が有効であることを確認
- 受信者の電話番号がWhatsAppに登録されていることを確認
- メッセージ形式とペイロード構造を検証
- テンプレートの承認状態を確認
- APIレート制限に達していないか確認