ビジネスメッセージ用のコンバージョンAPI: オンボーディングガイド

コンバージョンAPIは、アクセス許可を得たクライアントのデータをビジネスメッセージパートナーがサーバーから直接共有できるようにするMetaビジネスツールであり、Metaのユーザープライバシーコントロールを尊重するよう設計されています。これにより、ビジネスメッセージパートナーは、クライアントのビジネスチャットにおけるお客様とのインタラクションに関する貴重なデータを確実に送信できるようになり、WhatsApp、Messenger、Instagram誘導広告のパフォーマンスを把握し、運用効率化とビジネスの成長につなげることができます。

このガイドは、クライアントに代わって、ビジネスメッセージパートナーがWhatsApp、Messenger、InstagramのコンバージョンAPIの技術的連携を完了することを支援する目的で作成されています。内容は以下のとおりです。

連携前の要件
連携ステップ
コンバージョンAPIを使用したイベントの送信
イベントマネージャでイベントを確認する

注: コンバージョンAPIでは、広告主がウェブサイト、アプリ、オフライン(実店舗を含む)、CRMのイベントをMetaに送信することもできます。現在、ほかの利用方法でコンバージョンAPIを連携しているビジネスメッセージパートナーも、以下の手順に従ってビジネスメッセージ用のコンバージョンAPIと連携する必要があります。

Messenger誘導広告

連携前の要件

連携を開始する前に、技術基盤が正しく確立され、特定のアセットやプラットフォームに関連するアクセス権が付与されていることを確認する必要があります。

Facebook開発者アプリを作成する

アプリをまだ持っていない場合は、指示に従って作成します。

Messenger APIと連携する

下記のアドバンスアクセスが必要です。

page_eventsアクセス許可
- 開発者アプリダッシュボードの[アクセス許可と機能]セクションのpage_eventsアクセス許可へのアドバンスアクセスを申請する必要があります。すでに、pages_messagingアクセス許可のアドバンスアクセスがある場合は、申請後、アプリは自動的にpage_eventsアクセス許可を承認されます。
広告管理スタンダードアクセス機能。追加のガイダンスは、こちらをご覧ください。
- アドバンスアクセス機能を利用するには、過去15日間に1,500件以上のマーケティングAPI呼び出しを10％未満のエラー率で正常に実行している必要があります。これには、アプリの役割を持っているユーザーによるコンバージョンAPI経由の呼び出しが含まれます。

連携ステップ

1.アクセストークンを取得する

データセットAPIとコンバージョンAPIを呼び出すには、必要なアクセス許可を持つアクセストークンが必要です。

page_events

ビジネス用Facebookログインで生成されたトークンを再利用してください。

2.page_idを入手する

イベントを報告したいページのページIDを確認してください。

3.データセットを設定する

コンバージョンAPIを使ってMetaにイベントデータをシェアする場合、Metaはそのイベントに関連付けられているソースを知る必要があります。データセットを使用すると、ウェブサイト、モバイルアプリ、実店舗、ビジネスチャットなどさまざまなソースのイベントデータをリンクさせて一元的に管理できます。データセットについて、詳しくはこちらをご覧ください。

データセットは、パートナープラットフォーム経由で作成されるか、またはイベントマネージャで直接作成されます。ビジネスがデータセットを所有し、パートナーと提携している場合も、データセットへのアクセス権がパートナーに付与されます。

page_idとaccess_tokenを使ってデータセットAPIにPOST呼び出しを行い、データセットを作成します。既存のdataset_idがページに関連付けられている場合、そのIDが返されます。以下は呼び出しの例です。

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

応答はdataset_idを表すIDになります。このIDとビジネス用Facebookログインのアクセストークンを使用すれば、コンバージョンAPIを呼び出してMetaにメッセージイベントを送信できるようになります。

注: ビジネスアカウントにページが関連付けられていてbusiness_managementアクセス許可が付与されている場合、該当するデータセットがそのビジネスアカウントの下に表示されます。それ以外の場合、広告主には表示されません。

4.Page-Scoped ID (PSID)を取得する

Page-scoped ID (PSID)は、ユーザーとビジネス間の会話でのユーザーを表す識別子です。この識別子は、Messages Webhookを介して公開され、送受信API全体で使用されます。また、特定のユーザー(PSID)にマッピングされたコンバージョンイベントを送信する際にもコンバージョンAPIで使用されます。

シグナルを報告したいページのPSIDを確認してください。

コンバージョンAPIを使用したイベントの送信

連携の最終段階では、これまでの手順で取得したすべての情報(access_token、page_id、dataset_id、PSID)を使用してコンバージョンAPI経由でイベントを送信することができます。

キャンペーン期間中、イベントがリアルタイムで発生するたびに、dataset_idとaccess_tokenを使用してコンバージョンAPI経由でイベントをMetaに通知します。このAPIに対してPOSTリクエストを送信します。

https://graph.facebook.com/v16.0/{DATASET_ID}/events?access_token={TOKEN}

以下は、単一の購入イベントのAPI呼び出しの例です。

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "messenger",
      "user_data": {
        "page_id": <PAGE_ID>,
        "page_scoped_user_id": <PSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

イベントマネージャでイベントを確認する

イベントがコンバージョンAPIを介してMetaに正常に送信されると、イベントマネージャでそのイベントが特定のデータセットに反映されていることを確認できるはずです。詳しくは、イベントマネージャとその使用についてこちらでご覧ください。

注: パートナーの場合、イベントが受信されたことを確認するために、イベントマネージャのデータセットにアクセスする方法について広告主に指示を与えてください。

WhatsApp誘導広告

連携前の要件

Facebook開発者アプリを作成する

アプリをまだ持っていない場合は、指示に従って作成します。

下記のアドバンスアクセスが必要です。

whatsapp_business_managementアクセス許可
whatsapp_business_manage_eventsアクセス許可
- 開発者アプリダッシュボードの[アクセス許可と機能]セクションのwhatsapp_business_manage_eventsアクセス許可のアドバンスアクセスを申請する必要があります。すでにwhatsapp_business_messagingアクセス許可のアドバンスアクセスがある場合は、申請後、アプリは自動的にwhatsapp_business_manage_eventsアクセス許可を承認されます。
広告管理スタンダードアクセス機能を使用すると、アプリはマーケティングAPIを利用できるようになります。追加のガイダンスは、こちらをご覧ください。
- アドバンスアクセス機能を利用するには、過去15日間に1,500件以上のマーケティングAPI呼び出しを10％未満のエラー率で正常に実行している必要があります。これには、アプリの役割を持っているユーザーによるコンバージョンAPI経由の呼び出しが含まれます。

以下の2つのWhatsApp Businessプラットフォーム連携オプションのいずれかと連携させます。

MetaホスティングによるクラウドAPI(推奨)
オンプレミスAPI(*Biz APIバージョン: 2.45.1): ctwa_clidは、コンバージョンAPI経由でイベントを送信するための必須フィールドです。これは、Biz API バージョン2.45.1以降のMessages Webhookでのみ利用可能です。注: WhatsApp Businessプラットフォームは、今後2年間で次世代クラウドAPIに完全に移行します。オンプレミスAPIクライアントの最後のサポート対象バージョンは、2025年10月23日に期限切れとなります。詳しくはこちらをご覧ください。

認証と承認のためにログインソリューションと連携する(埋め込み登録、ビジネス用Facebookログイン)

連携ステップ

1.アクセストークンを取得する

データセットAPIとコンバージョンAPIを呼び出すには、必要なアクセス許可を持つアクセストークンが必要です。

whatsapp_business_management
whatsapp_business_manage_events

埋め込み登録と連携している場合は、埋め込み登録フローで生成されたトークンを再利用することをおすすめします。または、必要なアクセス許可がある場合に限り、ビジネス連携システムユーザーアクセストークン、システムユーザーアクセストークン、ユーザーアクセストークンのいずれかを使用することができます。

2.WhatsApp BusinessアカウントIDを取得する

WhatsApp BusinessアカウントID(waba_id)は、埋め込み登録フローを完了すると取得できます。詳しくはこちらをご覧ください。

3.データセットAPIを設定する

コンバージョンAPIを使ってMetaにイベントデータをシェアする場合、Metaはそのイベントに関連付けられているソースを知る必要があります。データセットを使用すると、Meta Businessソリューションパートナーがクライアントのウェブサイト、モバイルアプリ、実店舗、ビジネスチャットなどのさまざまなソースのイベントデータに接続して一元的に管理できるようになります。データセットの詳細はこちらをご覧ください。データセットはクライアントが所有し、必要なアクセス許可を持つMeta Businessソリューションパートナーがアクセスできます。

whatsapp_business_account_idとaccess_tokenを使用して、データセットAPIに対してPOST呼び出しを行い、データセットを作成できます。既存のdataset_idがWhatsApp Businessアカウントにすでに関連付けられている場合、そのIDが返されます。以下は呼び出しの例です。

https://graph.facebook.com/v16.0/{WHATSAPP_BUSINESS_ACCOUNT_ID}/dataset?access_token={TOKEN}

dataset_idを取得するには、whatsapp_business_account_idとaccess_tokenを使用してデータセットAPIへのGET呼び出しを行います。以下は呼び出しの例です。

https://graph.facebook.com/v16.0/{WHATSAPP_BUSINESS_ACCOUNT_ID}/dataset?access_token={TOKEN}

応答はdataset_idを表すIDになります。これでデータセットが設定され使用可能になりました。次に、コンバージョンAPI呼び出しでイベントを送信するために必要なctwa_clidを取得しなければなりません。

4.WhatsApp誘導広告クリックIDを取得する

WhatsApp誘導広告クリックID(ctwa_clid) は、個人識別子であり、クリックごとにユニークです。これは、WhatsApp誘導広告から開始される会話にユーザーが参加したときにビジネスに公開されます。この識別子は、コンバージョンAPI呼び出しを介してMetaに送り返す必要があります(以下のセクションを参照してください)。

ctwa_clidフィールドは、Messages Webhookの下にある参照オブジェクトから取得します(クラウド API | オンプレミス)。

ctwa_clidを受け取ったら、会話と一緒に保存します。会話内でコンバージョンが生じたとき、対応するctwa_clidをコンバージョンAPIを介して送信します。ctwa_clidが含まれる参照オブジェクトで受け取ったメッセージの例を以下に示します。

{
  "data": [
    {
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher "
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "from": "12345678",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "referral": {
        "body": "This is a great product",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
        "headline": "Our new product",
        "image": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45"
        },
        "source_id": "1234567890",
        "source_type": "ad",
        "source_url": "https://fb.me/AAAAA"
      },
      "text": {
        "body": "Can I learn more about your business?"
      },
      "timestamp": "1678189586",
      "type": "text"
    }
  ]
}

コンバージョンAPIを使用したイベントの送信

連携の最終段階では、これまでの手順で取得したすべての情報(waba_id、dataset_id、ctwa_clid)を使用してコンバージョンAPI経由でイベントを送信することができます。

広告主のキャンペーン期間中、イベントはリアルタイムで生じます。dataset_idとアクセストークンを使用して、コンバージョンAPI経由でこれらのイベントをMetaに通知します。このAPIに対してPOSTリクエストを送信します。

https://graph.facebook.com/v16.0/{DATASET_ID}/events?access_token={TOKEN}

以下は、単一の購入イベントのAPI呼び出しの例です。

{
  "data": [
    {
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "whatsapp_business_account_id": <WHATSAPP_BUSINESS_ACCOUNT_ID>,
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

イベントマネージャでイベントを確認する

Instagram Direct誘導広告

連携前の要件

Facebook開発者アプリを作成する

アプリをまだ持っていない場合は、指示に従って作成します。

Messenger APIと連携する

下記のアドバンスアクセスが必要です。

instagram_manage_eventsアクセス許可
- 開発者アプリダッシュボードの[アクセス許可と機能]セクションで、instagram_manage_eventsアクセス許可へのアドバンスアクセスを申請する必要があります。instagram_manage_messagesアクセス許可のアドバンスアクセスがすでにある場合は、アプリは自動的にinstagram_manage_eventsアクセス許可を承認されます。
広告管理スタンダードアクセス機能。追加のガイダンスは、こちらをご覧ください。
- アドバンスアクセス機能を利用するには、過去15日間に1,500件以上のマーケティングAPI呼び出しを10％未満のエラー率で正常に実行している必要があります。これには、アプリの役割を持っているユーザーによるコンバージョンAPI経由の呼び出しが含まれます。

連携ステップ

1.アクセストークンを取得する

データセットAPIとコンバージョンAPIを呼び出すには、必要なアクセス許可を持つアクセストークンが必要です。

instagram_manage_events

ビジネス用Facebookログインで生成されたトークンを再利用してください。

2.`instagram_user_id`を取得する

イベントを報告したいInstagramアカウントのinstagram_user_idを確認してください。

3.データセットを設定する

instagram_user_idとaccess_tokenを使って、データセットAPIに対してPOST呼び出しを行い、データセットを作成します。既存のdataset_idがIGユーザーにすでに関連付けられている場合、そのIDが返されます。以下は呼び出しの例です。

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

応答はdataset_idを表すIDになります。このIDとビジネス用Facebookログインのアクセストークンを使用すれば、コンバージョンAPIを呼び出してMetaにメッセージイベントを送信できるようになります。

4.Instagram-scoped ID (IGSID)を取得する

Instagram-scoped ID(IGSID)は、userと<>ビジネス間の会話でのユーザーを表す識別子です。この識別子は、MessagesWebhookを介して公開され、送受信API全体で使用されます。これは、特定のユーザー(IGSID)にマッピングされたコンバージョンイベントを送信する際に、コンバージョンAPIでも使用されます(詳細は、次のセクションで説明します)。

イベントを報告したいInstagramアカウントのIGSIDを確認してください。

コンバージョンAPIを使用してイベントを送信する

連携の最終段階では、これまでの手順で取得したすべての情報(dataset_id、アクセストークン、instagram_user_id、IGSID)を使用してコンバージョンAPI経由でイベントを送信することができます。

キャンペーン期間中、イベントがリアルタイムで発生するたびに、dataset_idとアクセストークンを使用してコンバージョンAPI経由でイベントをMetaに通知します。このAPIに対してPOSTリクエストを送信します。

https://graph.facebook.com/v16.0/{DATASET_ID}/events?access_token={TOKEN}

以下は、単一の購入イベントのAPI呼び出しの例です。

{    
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "instagram",
      "user_data": {
        "instagram_business_account_id": <instagram_business_account_id>,
        "ig_sid": <IGSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

イベントマネージャでイベントを確認する

よくある質問

ビジネスメッセージ用のコンバージョンAPIはどのようなタイプのメッセージイベントをサポートしていますか？

A: ビジネスメッセージ用のコンバージョンAPIは、ビジネスメッセージの次の種類のイベントをサポートするようになりました。

Purchase
LeadSubmitted
InitiateCheckout
AddToCart
ViewContent
OrderCreated
OrderShipped
OrderDelivered
OrderCanceled
OrderReturned
CartAbandoned
QualifiedLead
RatingProvided
ReviewProvided

メッセージイベントはメッセージスレッドで発生する顧客とのやり取りのみを表すものであり、ウェブサイトなどのほかのチャネルで発生するコンバージョンではありません。連携プロセスの際に対応するアクションソースを選択することで、イベントを簡単に区別することができます。

異なるコンバージョンAPIの連携で、同じアプリを使用するか別のアプリを使用するかについて、Metaからのガイダンスはありますか？

A: パートナーから送信されたイベントをMetaが特定できるように、パートナーが1つのアプリを使用することがベストプラクティスです。すでに複数のアプリを持っているパートナーの場合は、partner_agentが自分に割り当てられたパートナーエージェント名に設定されていることを確認してください。不明な点がある場合は、Meta担当者にご相談ください。

メッセージスレッドの外(例えば、自分のウェブサイトやアプリ)でコンバージョンが発生した場合、イベントをMetaに渡すにはどうすればよいでしょうか？

A:メッセージングスレッド外でコンバージョンが発生した場合、関連するコンバージョンAPI製品を使用してそのイベントをMetaに送り返してください。例えば、自分のウェブサイトでコンバージョンが発生した場合、ウェブ用のコンバージョンAPIを使用します。自分のアプリでコンバージョンが発生した場合、アプリイベントのコンバージョンAPIを使用してください。イベントは引き続きウェブのコンバージョンAPIのクリックIDにアトリビューションされます。パラメーターの全リストはここにあります。

コンバージョンAPIでメッセージ誘導広告の最適化をすることはできますか？

A: コンバージョンAPIで購入最適化ができるのは、Messenger誘導広告とWhatsApp誘導広告のみです。現時点ではInstagram誘導広告の最適化はできません。Instagram誘導広告では、広告キャンペーンを最適化して会話を増やすことができます。

ビジネスメッセージ用のコンバージョンAPIの既存のデータセットを再利用できますか？

A: はい、既存のデータセットとのリンクをサポートしています。利用可能なオプションを参照して、ビジネスに適切なオプションをご決定ください。

現在ウェブサイト用のコンバージョンAPIを使用している場合、同じ連携にビジネスメッセージを追加すると、既存の連携が妨げられますか？

A: 既存のCAPI連携にビジネスメッセージを追加することにリスクはありません。アトリビューションはページ/データセットIDに基づいており、アプリIDとは関係ありません。

ページにリンクできるデータセットの数は？

A: ページにリンクできるデータセットは1つのみです。

ビジネスメッセージ用のコンバージョンAPIでイベントを送信する前に、イベントを重複除外する必要がありますか？

A: Metaは、ビジネスメッセージ用のコンバージョンAPIのイベントの重複除外をサポートしていないため、広告主はビジネスメッセージ用のコンバージョンAPIでイベントを送信する前に重複除外を行うことを強くおすすめします。

参考情報

コンバージョンAPIの概要
コンバージョンAPIの使用
コンバージョンAPIのパラメーター
ベストプラクティス
WhatsApp Businessプラットフォーム(オンプレミスまたはクラウドAPI)ビジネスAPIバージョン2.45.1以降
InstagramメッセージAPI