aws-social-messaging

AWS End User Messaging Social — WhatsApp

概要

AWS End User Messaging Social を介した WhatsApp メッセージング：テンプレート管理、メッセージ送信、メディア処理、イベント送信先、配信に関するトラブルシューティング。

推奨セットアップ： サンドボックス化された実行、監査ログ、エンタープライズ向け制御には、AWS MCP サーバーを使用してください。

AWS MCP を使用しない場合： AWS CLI にアクセスできるあらゆるエージェントで、このスキルを使用できます。すべてのコマンドは標準の AWS CLI 構文を使用します。

一般的なタスク

1. 依存関係を確認する

制約：

• シームレスな API 実行には AWS MCP サーバーを推奨しますが、必須ではありません。すべてのコマンドは標準の AWS CLI 構文を使用します
• AWS CLI がインストールされ、適切な認証情報で設定されていることを必ず確認してください
• ユーザーには、一時的な認証情報を使用する IAM ロールを引き受けることを推奨してください
• 必要なツールが不足している場合は、その旨とインストール方法や設定方法を必ずユーザーに伝えてください
• 不足しているツールがあっても続行するかどうかを必ずユーザーに尋ねてください
• aws socialmessaging サブコマンドが認識されない場合は、AWS CLI を最新バージョンに更新する必要があります
• 必要な IAM 権限（特定の WABA および電話番号の ARN に範囲を限定してください）：
  • テンプレート：social-messaging:CreateWhatsAppMessageTemplate、social-messaging:GetWhatsAppMessageTemplate、social-messaging:ListWhatsAppMessageTemplates、social-messaging:UpdateWhatsAppMessageTemplate、social-messaging:DeleteWhatsAppMessageTemplate、social-messaging:ListWhatsAppTemplateLibrary、social-messaging:CreateWhatsAppMessageTemplateFromLibrary
  • 送信：social-messaging:SendWhatsAppMessage
  • メディア：social-messaging:PostWhatsAppMessageMedia、social-messaging:CreateWhatsAppMessageTemplateMedia、social-messaging:GetWhatsAppMessageMedia、social-messaging:DeleteWhatsAppMessageMedia
  • イベント：social-messaging:PutWhatsAppBusinessAccountEventDestinations
  • 診断：social-messaging:GetLinkedWhatsAppBusinessAccount、social-messaging:GetLinkedWhatsAppBusinessAccountPhoneNumber、social-messaging:ListLinkedWhatsAppBusinessAccounts
  • 補助：sns:ListSubscriptionsByTopic、iam:PassRole（イベント送信先ロール用）

2. テンプレートを管理する

メッセージテンプレート（ユーティリティ、マーケティング、認証）を作成、更新、削除します。

• create-whatsapp-message-template：--template-definition（blob 型）を Base64 エンコードします
• create-whatsapp-message-template-from-library：Meta の事前承認済みライブラリテンプレートを使用します
• list-whatsapp-template-library：利用可能なライブラリテンプレートを参照します
• get-whatsapp-message-template：--id（WABA）と --meta-template-id でテンプレートの詳細を取得します
• update-whatsapp-message-template：既存のテンプレート内容を変更します
• delete-whatsapp-message-template：--template-name（--meta-template-name ではありません）が必要です。必ず --delete-all-languages を指定してください
• list-whatsapp-message-templates：レスポンスフィールドは templateStatus と templateCategory です（status／category ではありません）
• {{N}} パラメーターを含むテンプレートでは、"parameter_format": "positional"（例外：AUTHENTICATION — OTP パラメーターは Meta が自動的に処理します）と "example" を必ず指定してください
• Meta はすべてのテンプレートを審査します（数分から 24 時間）。PENDING／REJECTED のテンプレートでメッセージを送信してはなりません
• カテゴリを誤って選ぶと再分類（UTILITY → MARKETING）が発生し、料金が変わります。UTILITY、MARKETING、AUTHENTICATION の選択方法については、managing-templates.md — 適切なカテゴリの選択を参照してください
• テンプレートを作成する前に、意図するカテゴリ（UTILITY、MARKETING、AUTHENTICATION）を必ずユーザーに確認してください。選択が曖昧な場合は、分類基準と再分類のリスクを説明してください

managing-templates.mdを参照してください。

3. メッセージを送信する

テンプレートメッセージ（24時間の制限なし）

• 用途：取引に関する更新（ユーティリティ）、プロモーション（マーケティング）、認証コード（認証）
• 必要な情報：電話番号 ID、宛先（+ 付きの E.164 形式）、テンプレート名、言語、パラメーター
• マーケティングテンプレートには画像ヘッダーを含められます
• --message は blob 型です。JSON を必ず base64 エンコードしてください

自由形式メッセージ（24時間以内のウィンドウが必要）

• 用途：顧客から最後に受信したメッセージから24時間以内のカスタマーサービス返信
• 対応形式：テキスト、画像、ドキュメント、動画、音声。対応する形式とサイズの制約については、WhatsApp Cloud API メディアリファレンスを参照してください
• ウィンドウの状態を確認する API はありません。ユーザーはログまたはイベント履歴で確認する必要があります
• メディア URL は、誰でもアクセスできる HTTPS である必要があり、メッセージの30日間の利用可能期間中、アクセス可能な状態を保つ必要があります（Meta はいつでも再取得できます）。機密性の高いコンテンツ（領収書、請求書、PII）には、post-whatsapp-message-media 経由でアップロードし、代わりにメディア ID を指定してください。署名付き URL は30日間の利用可能要件を満たせません

すべての送信に関する制約：

• API 呼び出しを実行する前に、パラメーターの形式を検証してください：
  • 電話番号 ID は phone-number-id-* のパターンに一致する必要があります
  • WABA ID は waba-* のパターンに一致する必要があります
  • 宛先番号は + を接頭辞とする E.164 形式（例：+14155551234）、または "recipient" フィールドを介したビジネススコープユーザー ID（BSUID）である必要があります
  • テンプレート名には小文字、数字、アンダースコアのみを使用してください
  • 言語コードには、アンダースコアを使った Meta のロケール形式を使用してください（例：en_US、pt_BR）
  • --meta-api-version は v{Major}.{Minor} 形式である必要があります（例：v21.0）
• JSON 本文の "messaging_product" は必ず "whatsapp" にしてください。サポート対象の Meta Graph API バージョンについては、Meta の Graph API 変更履歴を確認してください
• --message は blob 型です。JSON ペイロードを必ず base64 エンコードしてください
• messageId が正常に返されても、意味するのはキューに登録されたことであり、配信されたことではありません
• 必須パラメーターはすべて、単一のプロンプトで事前に確認する必要があります
• パラメーターは個別の値、JSON オブジェクト、またはファイル参照で受け付ける必要があります
• 実行前に各手順を説明する必要があります
• 実行前に、すべてのパラメーターをユーザーに確認することが推奨されます
• 中止するというユーザーの判断を尊重する必要があります
• ユーザーの確認なしに、1回のバッチで5件を超えるメッセージを送信してはいけません
• 認証情報を直接作成またはアクセスしてはいけません

メッセージの送信を参照してください。

4. メディアを管理する

メッセージやテンプレートヘッダー用のメディアをアップロード、取得、削除します。

• post-whatsapp-message-media：メディアをアップロードし、再利用可能なメディア ID を返します
• create-whatsapp-message-template-media：テンプレートヘッダー専用のメディアをアップロードします
• get-whatsapp-message-media：ID を指定してメディアのメタデータ／URL を取得します
• delete-whatsapp-message-media：アップロードしたメディアを削除します

メディアの管理を参照してください。

5. イベントの送信先を設定する

配信の追跡、テンプレートのステータス通知、再分類アラートを設定します。

配信の追跡、テンプレートのステータス通知、再分類アラートを設定します。WABA に設定できるイベント送信先は1つだけです。前提条件（IAM ロール、KMS 暗号化を使用する SNS トピック、HTTPS のみのサブスクリプションエンドポイント、条件キー）とセキュリティ制御の詳細については、イベント送信先の設定を参照してください。

6. 配信のトラブルシューティング

診断の流れ：WABA のステータス → 電話番号 → テンプレート → イベントの宛先 → クォータ。

• get-linked-whatsapp-business-account：登録が COMPLETE である必要があります
• get-linked-whatsapp-business-account-phone-number：電話番号の状態を確認します
• list-linked-whatsapp-business-accounts：すべての WABA を一覧表示します
• テンプレートのカテゴリが変更された場合：イベントの宛先（リアルタイム）で検出するか、テンプレートを一覧表示してカテゴリを比較します。削除して再作成してください
• 24 時間のウィンドウが期限切れの場合：代わりにテンプレートメッセージを使用します
• レート制限：新しい WABA の上限は低く、品質の向上に伴って引き上げられます
• WhatsApp を利用していない受信者：通知なしで破棄されます

troubleshooting-delivery.mdを参照してください。

クイックリファレンス — よくあるエラー

• アクセス拒否：WABA／電話番号 ARN に範囲を限定した IAM 権限を確認してください
• テンプレートが拒否された：本文はカテゴリに一致する必要があります。parameter_format と example を含めてください
• テンプレートのカテゴリが変更された：検出できるようイベントの宛先を設定してください。削除して再作成してください
• 24 時間のウィンドウが期限切れ：自由形式のメッセージではなく、テンプレートメッセージを使用してください
• 送信に失敗する：--origination-phone-number-id は ID（電話番号ではありません）です。受信者の電話番号は + を含む E.164 形式にしてください
• キューに入ったが配信されない：200 = キューに登録済みです。ステータスを確認するにはイベントの宛先を設定してください
• メディア URL にアクセスできない：一般にアクセス可能な HTTPS URL である必要があります

セキュリティに関する考慮事項

• 特定の social-messaging: アクションと WABA／電話番号 ARN に範囲を限定した最小権限の IAM ポリシーを使用します
• 長期間有効なアクセスキーではなく、一時的な認証情報（IAM ロール）を使用します
• シークレットは AWS Secrets Manager または Parameter Store に保存します。コードや環境変数には決して保存しないでください
• すべての social-messaging API 呼び出しを監査できるよう CloudTrail を有効にし、ログを KMS CMK で暗号化します
• イベントの宛先に使用する SNS トピックを KMS で暗号化します（コールバックには受信者のメタデータが含まれます）
• social-messaging のアクティビティを監視する場合は、CloudWatch Logs を KMS で暗号化します
• テンプレートパラメーターや自由形式のメッセージ本文に機密データを含めないでください（CloudTrail ログに記録されます）
• 不正なメッセージ送信を防ぐため、受信者の電話番号を検証します
• SNS サブスクリプションのエンドポイントがチームによって承認されていることを確認します。サブスクリプションを確定する前に、登録されているすべてのメールアドレスとシステムが、機密性の高い配信ステータスや受信者のメタデータを受け取るべき担当者／システムのものであることを検証してください。HTTPS のみのエンドポイントを使用します
• 混乱した代理人攻撃を防ぐため、SNS トピックポリシーに条件キー（aws:SourceArn、aws:SourceAccount）を追加します
• サービスクォータと送信レートに関する CloudWatch アラームを使ってレート制限を実装します

その他のリソース

• AWS End User Messaging Social ユーザーガイド
• AWS CLI socialmessaging リファレンス
• WhatsApp の使用開始
• イベントの宛先の管理
• サービスクォータ
• IAM セキュリティのベストプラクティス
• 混乱した代理人の防止
• SNS データ保護のベストプラクティス
• AWS Well-Architected セキュリティの柱