messaging-performance-analyzer

メッセージ配信パフォーマンス分析

概要

このスキルを使うと、Sent メッセージの生データを基に、何が変化したのか、ファネルのどこで離脱が発生しているのか、何を優先して修正すべきかを簡潔に診断できます。キャリア、WhatsApp、RCS のプロバイダーコードを解釈する前に、すべての分析の根拠をSent メッセージ ID、メッセージステータス、メッセージアクティビティ、Webhook イベントに置いてください。

Sent の v3 送信エンドポイントはテンプレートベースのリクエストを受け付け、非同期追跡用に受信者ごとの message_id を返します。ステータスは GET /v3/messages/{id} で取得し、詳細なライフサイクルの証跡は GET /v3/messages/{id}/activities で取得します。Webhook エンドポイントでは、イベントの取り込み、イベントタイプの検出、イベント履歴の確認、テスト配信、シークレットのローテーションができます。

使用するタイミング

メッセージが失敗した理由、配信率や既読率が低下した理由、フォールバックが機能しているか、プロバイダーがトラフィックをフィルタリングしているか、キャンペーンがどのような成果を上げたかをユーザーが尋ねた場合に、このスキルを使用してください。「MDR」「配信レポート」「Webhook イベント」「アクティビティ」「ステータス」「失敗」「未配信」「既読率」「フォールバック」「フィルタリング」「スロットリング」「キャリア拒否」などの語句があれば、このスキルを使用します。

10DLC の登録、Sender Profile の設計、RCS のオンボーディング、WhatsApp テンプレートの作成には、このスキルを使用しないでください。パフォーマンス上の問題を特定した後、関連するスキルにそれらのワークフローを引き継いでください。

証拠の優先順位

まず Sent が管理する証拠を確認し、次にプロバイダーの情報を加えてください。これにより、欠落していたり、古かったり、チャネル間で正規化の方法が異なったりするキャリアコードに過度に依存するのを防げます。

証拠	Sent で確認できる経路	用途
送信レスポンス	POST /v3/messages	リクエスト ID、受け付けられた受信者、チャネルごとの送信先、および Sent の message_id を特定します。
現在のステータス	GET /v3/messages/{id}	最新の既知のライフサイクルステータスと、API に表示されるエラーの詳細を確認します。
アクティビティのタイムライン	GET /v3/messages/{id}/activities	受付、ルーティング、送信、配信、既読、エラーへの遷移を再構成します。
Webhook の設定	GET /v3/webhooks、GET /v3/webhooks/event-types	顧客が分析に必要なイベントを購読しているか確認します。
Webhook イベント履歴	GET /v3/webhooks/{id}/events	配信済みイベントを API のステータスおよび顧客の取り込みログと比較します。
Webhook の接続性	POST /v3/webhooks/{id}/test	配信インフラの問題を疑う前に、エンドポイントに到達できることを確認します。

手順

1. ファネルを分析する前に、質問を明確にする

ユーザーの質問を、測定可能な比較として言い換えてください。「WhatsApp の調子が悪い」は、「月曜日から水曜日にプロフィール A から送信された注文テンプレートの WhatsApp DELIVERED 率が低下したか」のようにします。質問を具体化すると、コホートを一定に保ち、複数チャネルの平均値によって障害の原因が隠れるのを防げます。

計算を始める前に、プロフィールまたは送信者の ID、テンプレート ID／名前、チャネル、国、送信時間帯、受信者セグメント、フォールバックまたはマルチチャネルブロードキャストが要求されたかどうかというディメンションを記録してください。

例。 ユーザーが「RCS のフォールバックが機能しなくなった」と言った場合、コホートを channel を省略した送信、または channel: ["sent"] を使用した送信と定義し、選択された payload.channel とメッセージアクティビティを比較します。明示的な複数チャネル配列はブロードキャストとして別途分析してください。

2. Sent のメッセージ ID からコホートを作成する

Sent の message_id を基本単位として使用します。複数のチャネルを指定すると、v3 の送信では受信者とチャネルの組み合わせごとに個別のメッセージが作成されることがあります。終端結果の集計では、Sent の各メッセージを 1 回だけ数え、重複排除してから受信者単位またはキャンペーン単位の集計を追加します。

アクティビティ履歴と最新ステータスのスナップショットを区別します。履歴からは、履歴に含まれる遷移を確認できます。status=DELIVERED のようなスナップショットで確認できるのは、観測された現在の結果のみです。エクスポートで QUEUED、ROUTED、SENT も観測されたことの証明にはなりません。利用できない遷移の分母はゼロではなく N/A として報告し、欠落している遷移を決して捏造しないでください。

エクスポートされた証拠に Sent ID がない場合を除き、WhatsApp の wamid、SMS のキャリア ID、RCS のメッセージ ID などのプロバイダー ID を主な結合キーとして使用しないでください。プロバイダー ID はエスカレーションには役立ちますが、Sent API とダッシュボードでは Sent のメッセージ ID でステータスを追跡します。

3. ライフサイクルの段階を Sent が文書化しているステータスに正規化する

Sent が文書化している配信ライフサイクルを、最初のファネルとして使用します。QUEUED、ROUTED、SENT、DELIVERED です。READ は WhatsApp と RCS の個別のエンゲージメント指標として扱い、SMS の配信要件には含めないでください。終端失敗、延期中／処理中のメッセージ、インバウンドの RECEIVED メッセージ、不正形式／不明なレコードは、証拠に存在するフィールドのみを使って別々の区分に分類します。

段階	解釈	よくある診断上の質問
QUEUED	Sent が処理リクエストを受け付けました。	バックログが増加していますか、それともリクエストが一度もルーティングされていませんか？
ROUTED	Sent がチャネル／プロバイダーの経路を選択しました。	ルーティングでは想定されたチャネルまたはフォールバック経路が選択されましたか？
SENT	メッセージが Sent／プロバイダーの処理を離れ、宛先ネットワークに向かいました。	プロバイダーによる受け入れ数は多いのに、その後の配信数は少なくありませんか？
DELIVERED	対応している場合、配信が確認されました。	宛先ネットワークから受信確認がありましたか？
READ	利用可能な場合、WhatsApp／RCS のエンゲージメント受領確認が観測されました。	配信後にユーザーはメッセージを開きましたか？
エラー／失敗	終端エラーまたは回復可能なエラーが発生しました。	根本原因はコンプライアンス、ペイロード、スループット、オプトアウト、プロバイダーの障害のどれですか？

4. 配信を診断する前に Webhook の健全性を確認する

ダッシュボードのアクティビティや顧客側のイベントの減少は、配信ではなく Webhook の取り込みに関する問題である可能性があります。Webhook の存在、有効状態、イベントのサブスクリプション、最近のイベント履歴、テスト配信を確認してください。ユーザーが明示的に求めた場合、または認証情報の漏えいが疑われる場合に限り、シークレットをローテーションしてください。ローテーションすると、古いシークレットは直ちに無効になります。

例。 Sent のステータスが DELIVERED を示しているのに、顧客のデータベースに「配信コールバックなし」と表示される場合は、/v3/webhooks/{id}/events と顧客のエンドポイントログを調べます。Sent にイベントがある一方で、エンドポイントが失敗を返していた場合、必要なのは Webhook の処理の修正であり、キャンペーンのルーティングの修正ではありません。

5. 根本原因を特定する前にチャネルごとに分ける

SMS、WhatsApp、RCS では障害の種類が異なります。ユーザーが複合 KPI を明示的に求めた場合を除き、それらをまとめて平均しないでください。まず各チャネルのファネルを比較し、その後で全体を比較します。

チャネル	最初に確認する切り口	次に確認することが多い証拠
SMS	国、送信者／プロファイル、10DLC キャンペーン、オプトアウト、キャリア群	コンプライアンスの状態、ブランド／キャンペーンの準備状況、オプトアウトのログ、スループットのパターン。
WhatsApp	テンプレート、言語、カテゴリ、受信者の国、品質／ティアに関する兆候	テンプレートの状態、開封確認、会話ウィンドウ、存在する場合は Meta 側のエラー。
RCS	エージェントの準備状況、自動ルーティング、固定チャネルの失敗、テキスト／サジェスチョンチップのレンダリング	Sent の RCS 設定ステータス、選択された経路、正確なアクティビティ／エラーの詳細。

6. 修正を提案する前に影響を定量化する

件数と割合を併記してください。15 件中の失敗率が 40％の場合と、150,000 件中の失敗率が 4％の場合とでは、判断が異なります。全体の合計をすべてのチャネル × 方向グループと照合し、不完全なディメンションを黙って除外せず、明示的な unknown グループとして残してください。保留中のメッセージ、テストトラフィック、サンドボックスからの送信、再試行、チャネルへの重複ファンアウトなどの除外項目も含めてください。

実用的な分析表には、送信件数、最新ステータスの分布、失敗件数、ベースラインとの失敗率の差分、正確なエラー文字列／コードの上位項目、最初に観測されたタイムスタンプ、影響を受けたテンプレート、影響を受けた国、影響を受けたプロファイルを含めてください。

7. 診断を次のアクションにつなげる

最後に、主要な診断を 1 つ、確信度を 1 つ、次に行う検証ステップを 1 つ示してください。一般的な修正案を長々と列挙するのは避けてください。すべての提案を、観測された根拠に結び付けてください。

例。「最大の離脱は、サポートプロファイル support-us の SMS トラフィックで、ROUTED の後に発生しており、開始時刻は 14:10 UTC です。WhatsApp と RCS のコホートは安定しています。影響を受けたトラフィックでは、同じ注文状況通知テンプレートと米国の A2P ルートが使われています。まず Sent のブランド／キャンペーンのステータスとオプトアウト処理を確認してください。準拠している場合は、正確なメッセージ ID とアクティビティのタイムスタンプを添えてエスカレーションしてください。」

避けるべき、よくある誤った説明

Sent の webhook イベント履歴とエンドポイントの応答を確認するまでは、顧客側 webhook がないことから配信失敗を推測しないでください。Webhook の取り込み失敗は、配信失敗と同じような症状を引き起こすことがよくあります。

ベースライン、国、送信者／プロファイル、テンプレートと比較せず、小さなサンプルだけを根拠にキャンペーンを「キャリアによるフィルタリング」と判断しないでください。フィルタリングはコホートを切り分けた後の結論であり、「失敗」の言い換えではありません。

READ を普遍的な段階として扱わないでください。Sent は WhatsApp と RCS の開封確認を記録しますが、SMS は通常、開封確認に対応していません。

ブロードキャストとフォールバックを混同しないでください。channel を省略するか ["sent"] を指定すると自動ルーティングが有効になり、チャネルを 1 つ明示すると配信先が固定され、複数の値を明示すると個別のメッセージが作成されます。返された message_id はそれぞれ 1 回ずつ数え、選択されたチャネルを報告してください。

検証チェックリスト

• 分析では Sent の message_id を主要な単位として使用しています。
• コホートは時間枠、プロファイル／送信者の識別情報、テンプレート、チャネル、受信者セグメントによって固定されています。
• ステータスの集計には、Sent メッセージ ID ごとの最新の既知ステータスを使用しています。
• 遷移の集計には、観測されたアクティビティ履歴を使用し、最新ステータスのみから段階を補完していません。
• 保留中または処理中のメッセージは、除外するか、別途報告しています。
• SMS の配信分析は DELIVERED までとし、WhatsApp／RCS の READ はエンゲージメントとして分類しています。
• 不正な形式のバケットと明示的な unknown バケットを含め、全体およびチャネル × 方向の合計が照合されています。
• 症状がコールバックの欠落である場合、Webhook の設定、イベント履歴、エンドポイントのテスト結果を確認しています。
• 集計レートを報告する前に、チャネル固有の失敗を分けています。
• プロバイダーまたはキャリアのコードは観測されたとおりに正確に引用し、参照テーブルから推測して作り出していません。
• 最終的な提案では、次に行う検証ステップを 1 つと、その根拠となる証拠を示しています。

関連スキル

離脱の原因が米国の A2P SMS コンプライアンス、ブランド登録、キャンペーン登録、またはオプトイン／オプトアウトの証拠にある場合は、sms-10dlc-registration を使用してください。

症状の原因がリアルタイムの配信分析ではなく、RCS エージェントの承認、ローンチ準備、機能の不足、またはフォールバック設計にある場合は、rcs-agent-onboarding を使用してください。

問題がテナント／プロファイルの分離、Webhook のルーティング、認証情報のスコープ設定、または複数ブランドの送信者設計にある場合は、sender-profile-architect を使用してください。

根本原因が WhatsApp テンプレートのカテゴリ、審査ステータス、テンプレートのペイロード構造、または作成ワークフローにある場合は、waba-template-author または template-builder-ui を使用してください。

Sent 共通の用語とルーティングについては、sent スキルを使用してください。

バンドルされている参考資料とスクリプト

ファイル	種類	目的
references/mdr-status-codes.md	参照表	スキル本文に長いコード一覧を含めずに、観測された SMS、WhatsApp、RCS プロバイダーのエラーを標準化します。
references/performance-diagnosis-playbook.md	解説付きの例	最初に調査するシグナルを選ぶための決定木、チャネル固有の診断パターン、スキル間の引き継ぎマトリックス、エスカレーション基準をまとめています。
scripts/analyze_mdr_funnel.py	検証スクリプト	MDR エクスポート（CSV または JSON）を読み込み、チャネル × 方向別に結果をグループ化し、配信の遷移とエンゲージメントを分けて、形式不正または不明な行を保持します。スキルのルートディレクトリから実行します：python scripts/analyze_mdr_funnel.py path/to/mdr.csv（--threshold N、--show-errors、または --format json を使用できます）。終了コード 0 は遷移の違反が観測されなかったこと、2 は入力が不正または利用可能なコホートがないこと、3 は違反が観測されたことを示します。JSON では分母が利用できない場合は null を使用し、テキストでは N/A を使用します。
scripts/fixtures/good.json	フィクスチャ	正常なファネルを示す合成 MDR エクスポートです。
scripts/fixtures/bad.json	フィクスチャ	SENT→DELIVERED の低下率が意図的に 50% を超えるようにした合成 MDR エクスポートです。