ビジネスメッセージのイベントAPIを使用してイベントを記録する

メッセージイベントAPI廃止

メッセージイベントAPIは2025年9月に廃止されます。この廃止に備えるため、メッセージイベントAPIは2024年9月24日にリリースされるバージョン21.0以降、グラフAPIの将来のリリースではサポートされなくなります。
最新のグラフAPIへのアップデートをしないパートナーは、2025年9月の公式な製品廃止まで、グラフAPIバージョン20.0またはそれ以前を呼び出してメッセージイベントAPIにアクセスできます。
最新のグラフAPIにアップデートしないパートナーには、新しい統合のためにコンバージョンAPIを使用することをおすすめします。コンバージョンAPIについて、詳しくはこちらをご覧ください。

このガイドでは、アプリイベントおよびFacebookページイベントを記録して、ユーザーがどのようにMessengerエクスペリエンスでやり取りしたかを分析する方法について説明します。

開始する前に

次のものが必要です。

page_eventsアクセス許可
- アプリがすでにpages_messagingアクセス許可のAdvanced Accessを付与されていて、過去90日間にポリシーの違反がない場合、アプリレビューの申請を行うと自動的にこのアクセス許可のAdvanced Accessが付与されます。
クエリ対象のページに対してANALYZEタスクを実行できるユーザーがリクエストしたページアクセストークン

制限

現時点では、ヨーロッパまたは日本に拠点を置くビジネスやカスタマーはこのAPIを利用できません。

ポリシーと利用規約

イベントを記録する

イベントは、POSTリクエストをアプリのpage_activitiesエッジに送信して記録します。

https://graph.facebook.com/

リクエストの例

curl -X POST -H "Content-Type: application/json" -d '{
  "custom_events": [
    {
      "_eventName": "fb_mobile_purchase",
      "_valueToSum": 57.23,
      "fb_currency": "USD"
    }
  ],
  "advertiser_tracking_enabled": 1,
  "application_tracking_enabled": 1,
  "page_id": <PAGE_ID>,
  "page_scoped_user_id": <PSID>,
  "logging_source": "messenger_bot",
  "logging_target": "page"
}' https://graph.facebook.com/v21.0/<APP_ID>/page_activities?access_token=<PAGE_ACCESS_TOKEN>

フィールド_eventNameには、標準イベントを使用するようおすすめします。標準イベントだけが広告マネージャに報告され、広告のターゲット設定や最適化に利用できます(それが可能な場合)。

例: 広告マネージャのアトリビューションのために購入イベントを記録するには、イベント名fb_mobile_purchaseを使用します。

標準イベント名とパラメーターの全一覧については、アプリイベントAPIガイド(「アプリイベントスキーマ」セクション)を参照してください。

以下の表に、Messengerイベントを記録する際にエンドポイントに指定する必要があるプロパティと値を示します。

プロパティ	説明	値
`custom_events`	ログに記録するイベントの配列。標準イベントと適用できるパラメーターのリストについては、アプリイベントAPIガイドを参照してください。独自のアプリイベントを使用することもできます。配列に複数のイベントを指定できます。	カスタムイベントの詳細を指定するには、JSONエンコードの配列を使用します。
`page_id`	イベントのに関連付けられているページIDを指定します。	ボットに関連付けられているページのFacebookページIDを使用します。
`page_scoped_user_id`	イベントを記録するMessengerボットに関連付けられているpage-scoped user IDを指定します。	Webhookに指定したpage-scoped user IDを使用します。
`advertiser_tracking_enabled`	広告トラッキングを有効にするかどうかを指定します。	無効にする場合は`0`、有効にする場合は`1`を使用します。
`application_tracking_enabled`	アプリケーションレベルで広告トラッキングを有効にするかどうかを指定します。	無効にする場合は`0`、有効にする場合は`1`を使用します。
`logging_source`	イベントソースを指定します。	文字列`messenger_bot`を使用して、このイベントがMessengerボットから発生したことを示します。
`logging_target`	イベントが記録されるターゲットエンティティを指定します。	文字列`app`、`page`、`app_and_page`のいずれかを使用して、このイベントを受信するエンティティをコントロールします。詳しくは、アプリイベントのよくある質問をご覧ください

メッセージイベントAPIを使用したリードの報告

アプリがスレッド上のリード送信の報告を開始できるようになりました。lead_submittedイベントを使えば、セールスリードと思われるスレッド(ユーザーが連絡先情報を共有し、販売に関する連絡を求めてくる場合など)の報告をアプリで自動化できます。

このイベントは、特定のユーザーを潜在的なリードとして区別し、ビジネスがそのユーザーからのスレッドを優先するのに役立ちます。例えば、ビジネスはユーザーを潜在的なリードと判断する自動フローを設定し、ユーザーがそのようなフローを完了したときにこのイベントをトリガーし、潜在的なリードの可能性が高いスレッドとしてフラグを付けてライブエージェントに通知できます。

現時点では、この機能はオープンベータ版として利用可能であり、広告マネージャでの報告機能は統合済みです。そのため、リードデータが広告マネージャUIで報告されるようになる予定です。

スレッドで発生したリードイベントを報告するためのAPI呼び出しの例は次のとおりです。

curl -X POST -H "Content-Type: application/json" -d '{
  "custom_events": [
    {
      "_eventName": "lead_submitted"
    }
  ],
  "advertiser_tracking_enabled": 1,
  "application_tracking_enabled": 1,
  "page_id": <PAGE_ID>,
  "page_scoped_user_id": <PSID>,
  "logging_source": "messenger_bot",
  "logging_target": "page"
}' https://graph.facebook.com/v21.0/<APP_ID>/page_activities?access_token=<PAGE_ACCESS_TOKEN>

広告インサイトAPIを使用したリードの報告

報告されたリードイベントは広告インサイトAPIを使って可視化できます。このAPIを使うと、CTXキャンペーンにアトリビューションされたリードを可視化するための、高度な分析ダッシュボードを作成できます。

前提条件

このAPIを使う前に、アプリについて必ず、ads_readアクセス許可に関するアプリレビュープロセスを完了し、アドバンスアクセスを得ておいてください。

実行

広告キャンペーンレベルでのインサイト呼び出しの例は、次のようになります。

curl -G \
-d "date_preset=last_7d" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_CAMPAIGN_ID>/insights"

インサイトAPIは、必要な詳細レベルに応じて、広告アカウント、キャンペーン、広告セットレベルで呼び出すことができます。

以下は、リード獲得のための呼び出しです。

リード(アトリビューション分析された)
- /<OBJECT_ID>/insights?fields=actions
- 結果: action_type=onsite_converstion.lead_grouped

上記のアクションタイプの詳細な定義については、広告アクション統計のリファレンスを参照してください。

リード分類のベストプラクティス

広告主は、従来のリード獲得バーティカル(自動、専門サービス、金融サービス、B2B、教育、健康)の1つに属しています。
広告主は電話番号やメールアドレスなどの連絡先情報を求め、ユーザーはそれらの情報を提供します。
電話番号またはメールアドレスに関する質問の前には、何らかの修飾が付けられることがあります(例: 1-2 追加の質問)。
アプリ内でリード獲得テンプレートを提供している場合、デフォルトでリード獲得フローの末尾にこのシグナルを追加します。

注: 特に、電話番号が支払いやEコマースを目的として共有される市場では、すべてのスレッドにリードとして電話番号やメールアドレスを自動的にマーク付けすることはおすすめしません。

イベント記録の検証

アプリまたはページの管理者は、広告マネージャでイベントを調べて、設定が正しいことを検証できます。

Messenger用Analyticsに関する特別な注意事項

単一のアプリで複数のページのインタラクションを記録できます。この場合、それらすべてのページとのインタラクションから発生したイベントは同じアプリに表示されます。
複数のアプリが1つのページにリンクされていることがあります。この場合、ページがブロックされると、そのページにリンクしているすべてのアプリがfb_messenger_bot_stoppedイベントを受け取ります。
削除されたMessengerボットスレッドの数が、新規ユーザーアクティビティの数より多くなる場合があります。削除されたMessengerボットスレッドは、ユーザーがスレッドを削除した回数です。ユーザーがスレッドを削除した後でも、ページはさらにスレッドを開始することができます。追加されたスレッドはユーザーが削除できますが、削除すると削除されたMessengerボットスレッドの数が増えます。

プラットフォームプロバイダーの利用

ログ記録ターゲット

ビジュアルインターフェイスを使ってMessengerエクスペリエンスを構築できるプラットフォームでは、通常、接続しているすべてのページに機能を提供する中心的な1つのアプリを使用します。顧客が自分自身のイベントを見ることができるようにするには、logging_targetをpageまたはapp_and_pageに設定して、イベントを顧客のページに記録する必要があります。

ユーザーインターフェイス

ビジュアルエディターのコンテキストでは、ドラッグ可能なブロックを提供して、ユーザーがイベントを選択して追加パラメーターを定義するようにできます。これによりページ管理者は、Messengerフローを適切なイベントにマップできます。理想的には、ユーザーが標準イベント名をドロップダウンリストから選択できるようにしてください。標準イベントだけが広告マネージャに報告され、広告ターゲット設定と最適化に利用できるからです(それが可能な場合)。ユーザーのアクションに合う標準イベント名がなく広告レポートが必要なければ、自由形式のフィールドを提供して、ユーザーがカスタムイベント名とパラメーターを入力できるようにしたいと思うかもしれません。

アクセス許可

必要なpage_eventsアクセス許可は、アプリのFacebookログインフロー中に取得する必要があります。そのアクセス許可を、ログインボタンでリクエストされるアクセス許可スコープ、Facebook JavaScript SDK呼び出し、またはこのガイドに概説されている手動で構築したログインフローに追加しなければなりません。

その他のリソース

アプリイベントのベストプラクティスガイド: 各種アプリで使用するイベントに関する推奨事項が含まれています。