このドキュメントは、ビジネス電話番号から送信されたメッセージの数、WhatsApp Businessアカウント(WABA)のコンバージョンの数とそのコスト、特定のテンプレートが読まれた回数など、メッセージ、コンバージョン、テンプレートの分析を取得する方法について説明しています。
リクエスト時にWABAに関連付けられているビジネス電話番号とテンプレートの指標のみが応答に含まれます。
WhatsApp Businessアカウントのエンドポイントを使用して分析を取得します。
GET /<WHATSAPP_BUSINESS_ACCOUNT_ID> ?fields=<FIELDS>.<FILTERING_PARAMETER>
プレースホル��ー | 説明 | 値の例 |
---|---|---|
| 必須。 指標。次のいずれかの値を使用できます。 |
|
| 必須。 指標フィルタリングパラメーター。ドットを使用してフィルタリングパラメーターを追加します。 使用できる値については、以下をご覧ください。 |
|
analytics
フィールドは、特定のWABAに関連付けられている電話番号によって送受信されたメッセージの数とタイプを提供します。スレッドの指標については、スレッド分析をご覧ください。/{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}
を呼び出す際に、以下のパラメーターを追加できます。
名前 | 説明 (指定できるオプションについては、左側の列の矢印をクリックしてください。) |
---|---|
型: UNIXタイムスタンプ | 必須。 取得する分析の対象期間の開始日。 |
型: UNIXタイムスタンプ | 必須。 取得する分析の日付範囲の最終日。 |
型: 文字列 | 必須。 取得する分析の粒度。 |
型: 配列 | 任意。 分析取得の対象となる電話番号の配列。指定しない場合、当該WABAに追加されているすべての電話番号が含められます。 |
型: 配列 | 任意。 通知を取得するメッセージのタイプ(通知メッセージやカスタマーサポートメッセージ)。配列を指定し、通知メッセージの場合は |
型: 配列 | 任意。 分析取得の対象となる国。含める国の2文字の国コードを要素とする配列を指定します。指定しない場合、通信したことのあるすべての国について分析が返されます。 |
シナリオ: WABAに関連付けられているすべての電話番号で送受信されたメッセージの数を取得する必要があるとします。
ソリューションの提案: 呼び出すURLを作成し、フィルタリングパラメーターとしてstart
、end
、granularity
を含めます。次に、そのURLに対してGET
リクエストを発行します。
curl -i -X GET \
"https://graph.facebook.com/v20.0
/{whatsapp-business-account-ID}
?fields=analytics
.start(1543543200)
.end(1544148000)
.granularity(DAY)
&access_token={access-token}"
成功すると、応答としてリクエストしたデータが含まれるanalytics
オブジェクトが返されます。
{ "analytics": { "phone_numbers": [ "16505550111", "16505550112", "16505550113" ], "country_codes": [ "US", "BR" ], "granularity": "DAY", "data_points": [ { "start": 1543543200, "end": 1543629600, "sent": 196093, "delivered": 179715 }, { "start": 1543629600, "end": 1543716000, "sent": 147649, "delivered": 139032 }, { "start": 1543716000, "end": 1543802400, "sent": 61988, "delivered": 58830 }, { "start": 1543802400, "end": 1543888800, "sent": 132465, "delivered": 124392 } # more data points ] }, "id": "102290129340398" }
conversation_analytics
フィールドは、特定のWABAのコストとスレッドの情報を提供します。/{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}
を呼び出す際に、以下のパラメーターを追加できます。
名前 | 説明 (指定できるオプションについては、左側の列の矢印をクリックしてください。) |
---|---|
型: UNIXタイムスタンプ | 必須。 取得する分析の対象期間の開始日。 |
型: UNIXタイムスタンプ | 必須。 取得する分析の日付範囲の最終日。 |
型: 文字列 | 必須。 取得する分析の粒度。 |
型: 配列 | 任意。 分析取得の対象となる電話番号の配列。指定しない場合、当該WABAに追加されているすべての電話番号が含められます。 |
| 任意。 取り出す指標のリスト。空のリストを送信すると、すべてのタイプの指標についての結果が返されます。 |
| 任意。 スレッドカテゴリのリスト。空のリストを送信すると、すべてのカテゴリのスレッドについての結果が返されます。 |
| 任意。 スレッドタイプのリスト。空のリストを送信すると、すべてのタイプのスレッドについての結果が返されます。 |
| 任意。 スレッドの方向のリスト。空のリストを送信すると、スレッドのすべての方向についての結果が返されます。 |
| 任意。 指標に適用する内訳のリスト。空のリストを送信すると、内訳なしの結果が返されます。 |
分析データは、データ処理における細かな違いにより、請求書に記載される値とは異なる場合があります。
WABAに関連付けられている、特定の期間のスレッドとコストの情報を取得できます。必要なら、結果に対してフィルターと内訳を適用できます。例については、下記のコードサンプルをご覧ください。
シナリオ: あるWABAに関連付けられているすべての電話番号の、特定の月のスレッドとコストの情報をすべて取り出します。
ソリューションの提案: 呼び出すURLを作成し、以下のフィルタリングパラメーターを含めます。
start
: 期間の始め。この場合、指標を調べる対象月の始まり。end
: 期間の終わり。この場合、指標を調べる対象月の終わり。granularity
: 希望するデータポイント粒度。下記の例では、MONTHLY
を使っているため、各データポイントは1か月分のデータを表すことになります。phone_numbers
: 空配列を送信します。該当WABAに関連する全電話番号の情報が返されます。dimensions
: 可能なすべての内訳("CONVERSATION_CATEGORY"
、"CONVERSATION_TYPE"
、"COUNTRY"
、"PHONE"
)に設定します。この場合、country_codes
、metric_types
、conversation_types
、conversation_categories
を指定する必要はありません。これらのフィールドのいずれも送信しない場合は、選択可能なすべてのオプションが返されます。URLを設定したら、GETリクエストを発行します。
curl -i -X GET
"https://graph.facebook.com/v20.0
/{whatsapp-business-account-id}
?fields=conversation_analytics
.start(1685602800).end(1688194800)
.granularity(MONTHLY)
.phone_numbers([])
.dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY","PHONE"])
&access_token={access-token}"
成功すると、応答としてリクエストしたデータが含まれるconversation_analytics
オブジェクトが返されます。以下の例では、WABAに含まれる電話番号は1つだけです。
{ "conversation_analytics": { "data": [ { "data_points": [ { "start": 1685602800, "end": 1688194800, "conversation": 1558, "phone_number": "15550458206", "country": "US", "conversation_type": "REGULAR", "conversation_direction": "UNKNOWN", "conversation_category": "AUTHENTICATION", "cost": 15.58 }, { "start": 1685602800, "end": 1688194800, "conversation": 2636, "phone_number": "15550458206", "country": "US", "conversation_type": "REGULAR", "conversation_category": "MARKETING", "cost": 26.36 }, { "start": 1685602800, "end": 1688194800, "conversation": 2238, "phone_number": "15550458206", "country": "US", "conversation_type": "REGULAR", "conversation_category": "SERVICE", "cost": 22.38 }, { "start": 1685602800, "end": 1688194800, "conversation": 1782, "phone_number": "15550458206", "country": "US", "conversation_type": "REGULAR", "conversation_category": "UTILITY", "cost": 17.82 }, { "start": 1685602800, "end": 1688194800, "conversation": 1568, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_TIER", "conversation_category": "AUTHENTICATION", "cost": 15.68 }, { "start": 1685602800, "end": 1688194800, "conversation": 2716, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_TIER", "conversation_category": "MARKETING", "cost": 27.16 }, { "start": 1685602800, "end": 1688194800, "conversation": 2180, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_TIER", "conversation_category": "SERVICE", "cost": 21.8 }, { "start": 1685602800, "end": 1688194800, "conversation": 1465, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_TIER", "conversation_category": "UTILITY", "cost": 14.65 }, { "start": 1685602800, "end": 1688194800, "conversation": 1433, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_ENTRY_POINT", "conversation_category": "SERVICE", "cost": 14.33 } ] } ] }, "id": "102290129340398", }
シナリオ: あるWABAに関連付けられている特定の電話番号の、特定の期間におけるスレッドとコストの情報をすべて取り出します。結果には、利用できるすべての内訳を使うものとします。各データポイントで半時間分のデータを表すことが必要です。
ソリューションの提案: 呼び出すURLを作成し、以下のフィルタリングパラメーターを含めます。
start
: 期間の始め。 end
: 期間の終わり。granularity
: 希望するデータポイント粒度。下記の例では、HALF_HOUR
を使っているため、各データポイントは半時間分のデータを表すことになります。phone_numbers
: 必要な情報の対象となる電話番号。dimensions
: 可能なすべての内訳(CONVERSATION_CATEGORY
、CONVERSATION_TYPE
、COUNTRY
、PHONE
)に設定します。この場合、country_codes
、metric_types
、conversation_types
、conversation_categories
を指定する必要はありません。これらのフィールドのいずれも送信しない場合は、選択可能なすべてのオプションが返されます。URLを設定したら、GETリクエストを発行します。
curl -i -X GET \
"https://graph.facebook.com/v20.0
/{whatsapp-business-account-id}
?fields=conversation_analytics
.start(1685602800)
.end(1685689200)
.granularity(HALF_HOUR)
.phone_numbers(["19195552584"])
.dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY,PHONE"])
&access_token=your-access-token"
成功すると、リクエストしたデータが含まれるconversation_analytics
オブジェクトが応答として返されます。
{ "conversation_analytics": { "data": [ { "data_points": [ { "start": 1685602800, "end": 1685604600, "conversation": 4, "phone_number": "19195552584", "country": "US", "conversation_type": "REGULAR", "conversation_direction": "UNKNOWN", "conversation_category": "SERVICE", "cost": 0.0232 }, { "start": 1685602800, "end": 1685604600, "conversation": 4, "phone_number": "19195552584", "country": "US", "conversation_type": "REGULAR", "conversation_direction": "UNKNOWN", "conversation_category": "MARKETING", "cost": 0.0232 }, # ... more data points ] } ] }, "id": "102290129340398" }
シナリオ: あるWABAに関連付けられているすべての電話番号の、特定の期間におけるスレッドとコストの情報をすべて取り出します。結果では、内訳をスレッドタイプ別に示します。
ソリューションの提案: 呼び出すURLを作成し、以下のフィルタリングパラメーターを含めます。
start
: 期間の始め。 end
: 期間の終わり。granularity
: 希望するデータポイント粒度。下記の例では、MONTHLY
を使っているため、各データポイントは半月分のデータを表すことになります。phone_numbers
: 空配列を送信します。該当WABAに関連する電話番号の情報がすべて返されます。dimensions
: CONVERSATION_TYPE
に設定します。この場合、country_codes
、metric_types
、conversation_types
、conversation_directions
、conversation_categories
を指定する必要はありません。これらのフィールドのいずれも送信しない場合は、選択可能なすべてのオプションが返されます。URLを設定したら、GETリクエストを発行します。
curl -i -X GET
"https://graph.facebook.com/v20.0
/{whatsapp-buiness-account-id}
?fields=conversation_analytics
.start(1643702400).end(1646121600)
.granularity(MONTHLY)
.phone_numbers([])
.dimensions([CONVERSATION_TYPE])
&access_token={access-token}"
成功すると、応答としてリクエストしたデータが含まれるconversation_analytics
オブジェクトが返されます。
{ "data": [ { "data_points": [ { "start": 1643702400, "end": 1646121600, "conversation": 8500, "conversation_type": "REGULAR", "cost": 88.1010 }, { "start": 1643702400, "end": 1646121600, "conversation”: 1000, "conversation_type": "FREE_TIER", "cost": 0.0000 } { "start": 1643702400, "end": 1646121600, "conversation”: 250, "conversation_type": "FREE_ENTRY_POINT", "cost": 0.0000 } ] } ] }
リクエスト
curl -i -X GET \
"https://graph.facebook.com/v20.0
/{whatsapp-buiness-account-id}
?fields=conversation_analytics
.start(1685527200)
.end(1685613600)
.granularity(HALF_HOUR)
.conversation_categories(["MARKETING","AUTHENTICATION"])
.dimensions(["CONVERSATION_CATEGORY"])
&access_token={access-token}"
応答
{ "conversation_analytics": { "data": [ { "data_points": [ { "start": 1685529000, "end": 1685530800, "conversation": 2, "conversation_category": "AUTHENTICATION", "cost": 0.0128 }, { "start": 1685527200, "end": 1685529000, "conversation": 3, "conversation_category": "MARKETING", "cost": 0.0432 } ] } ] }, "id": "102290129340398" }
リクエスト
curl -i -X GET \
"https://graph.facebook.com/v20.0
/{whatsapp-buiness-account-id}
?fields=conversation_analytics
.start(1685527200)
.end(1685613600)
.granularity(HALF_HOUR)
.conversation_categories(["MARKETING","AUTHENTICATION"])
.dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE"])
&access_token={access-token}"
応答
{ "conversation_analytics": { "data": [ { "data_points": [ { "start": 1685527200, "end": 1685529000, "conversation": 3, "conversation_type": "REGULAR", "conversation_category": "MARKETING", "cost": 0.0432 }, { "start": 1685529000, "end": 1685530800, "conversation": 2, "conversation_type": "REGULAR", "conversation_category": "AUTHENTICATION", "cost": 0.0128 } ] } ] }, "id": "102290129340398" }
テンプレート分析は、テンプレートの送信、配信、読み取りの回数と、テンプレートの[URL]ボタンまたは[クイック返信]ボタンがクリックされた回数を報告します。
データはUTCタイムゾーンの日次単位で返され、最大過去90日分遡ることができます。テンプレート分析は、[WhatsAppマネージャ] > [メッセージテンプレート] > [テンプレートの詳細] > [インサイト]パネルにもあります。
MARKETING
またはUTILITY
のカテゴリに分類されたテンプレートでのみ利用可能です。テンプレート分析の不具合を報告するには、次の項目を選択してダイレクトサポートチケットを送信してください。
テンプレート分析を取得する前に、お持ちのWhatsApp Businessアカウントでテンプレート分析を確認する必要があります。WhatsAppマネージャまたはAPIを使用してテンプレート分析を確認することができます。APIを使って実行するには、次のリクエストを送信してください。
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true
確認すると、WhatsApp Businessアカウントのテンプレート分析のキャプチャが開始されます。一度確認したテンプレート分析を無効にすることはできません。
成功すると、APIはWhatsApp BusinessアカウントIDで応答します。以下はその例です。
{ "id": 102290129340398 }
名前 | 説明 | 値の例 |
---|---|---|
UNIXタイムスタンプ | 必須。 取得する分析の対象期間の開始タイムスタンプ。UTCタイムゾーンの日単位の粒度でテンプレート分析が提供されるため、0:00 UTC以外の開始タイムスタンプは前の0:00 UTCに修正されます。 |
|
UNIXタイムスタンプ | 必須。 取得する分析の日付範囲の最終日。UTCタイムゾーンの日単位の粒度でテンプレート分析が提供されるため、0:00 UTC以外の終了タイムスタンプは次の0:00 UTCに修正されます。 |
|
列挙 | 必須。 取得する分析の粒度。値は |
|
IDの配列 | 必須。 分析取得の対象となるテンプレートIDの配列。 最大10。 |
|
列挙の配列 | 任意。 ソリューションパートナーを通じて請求するビジネスは、 取得の対象となる指標の種類。省略されていたり空の配列であったりする場合、すべての指標タイプの分析が返されます。 使用可能な値:
コスト指標は、それぞれタイプと値を持つコストオブジェクトの配列として返されます。タイプは以下のようになります。
|
|
シナリオ: 1日間の期間を指定して、URLボタンを含む認証テンプレートとマーケティングテンプレートのすべてのテンプレート分析指標タイプを取得します。
リクエストの例
curl -g 'https://graph.facebook.com/v20.0
/109259195336416/template_analytics?start=1718064000&end=1718122745&granularity=daily&metric_types=cost%2Cclicked%2Cdelivered%2Cread%2Csent&template_ids=[1421988012088524%2C2632273056924580]' \
-H 'Authorization: Bearer EAAJB...'
応答の例
{ "data": [ { "granularity": "DAILY", "product_type": "cloud_api", // Only available to businesses in Marketing Messages Lite API alpha "data_points": [ { "template_id": "1421988012088524", "start": 1718064000, "end": 1718150400, "sent": 1, "delivered": 1, "read": 1, "cost": [ { "type": "amount_spent", "value": 0.01 }, { "type": "cost_per_delivered", "value": 0.01 } ] }, { "template_id": "2632273056924580", "start": 1718064000, "end": 1718150400, "sent": 1, "delivered": 1, "read": 1, "clicked": [ { "type": "url_button", "button_content": "Contact Support", "count": 1 } ], "cost": [ { "type": "amount_spent", "value": 0.03 }, { "type": "cost_per_delivered", "value": 0.03 }, { "type": "cost_per_url_button_click", "value": 0.03 } ] } ] } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MjQZD" } } }
個々のテンプレートのボタンクリック数のトラッキングは、そのcta_url_link_tracking_opted_out
フィールドをtrue
に設定すれば無効化できます。無効化されると、APIはクリックされたプロパティをテンプレート分析で返さなくなり、テンプレートのインサイトを表示する際にボタンのエンゲージメント/クリック数がWhatsAppマネージャに表示されなくなります。
POST /<TEMPLATE_ID> ?cta_url_link_tracking_opted_out=<OPT_OUT> &category=<TEMPLATE_CATEGORY>
プレースホルダー | 説明 | 値の例 |
---|---|---|
テンプレートID | 必須。 テンプレートID。 |
|
ブーリアン | 必須。 テンプレートのボタンクリック数のトラッキングが無効化されているかどうかを示します。テンプレートでのボタンクリック数のトラッキングは、 この値は、テンプレート作成時には |
|
文字列 | 必須。 テンプレートの現在のカテゴリ。 テンプレートのカテゴリを現在のカテゴリ以外の値に設定した場合、テンプレートのステータスは |
|
curl -X POST 'https://graph.facebook.com/v20.0
/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'
成功すると、APIは以下のように応答します。
{ "success": true }
各フィールドで指定可能なすべての値のリストについては、WhatsApp Businessアカウントの分析フィールドのグラフAPIリファレンスをご覧ください。