Messaging Insights API

Dokumen ini menjelaskan cara mendapatkan metrik secara terprogram untuk pesan yang dikirim atau diterima bisnis Anda. Messaging Insights API adalah ekstensi dari Page Insights API yang memungkinkan Anda mendapatkan informasi yang sama seperti di tab Insight Halaman pada Halaman Facebook Anda.

Sebelum Memulai

Panduan ini berasumsi bahwa Anda telah membaca Ringkasan Platform Messenger dan menerapkan komponen yang dibutuhkan untuk mengirim dan menerima pesan serta notifikasi.

Untuk melihat metrik Halaman Facebook milik Anda atau melakukan tugas ANALYZE, aplikasi Anda perlu:

ID Halaman untuk Halaman Facebook yang ingin Anda lihat metriknya
- Untuk pesan Instagram, ini adalah Halaman Facebook yang tertaut ke akun Profesional Instagram
Token Akses Halaman
Izin berikut:
- pages_messaging
- pages_read_engagement
- pages_show_list
- read_insights
Akses Standar

Untuk melihat metrik Halaman Facebook yang tidak Anda miliki atau tidak bisa melakukan tugas ANALYZE di Halaman, aplikasi Anda perlu:

ID Halaman untuk Halaman Facebook yang ingin Anda lihat metriknya
- Untuk pesan Instagram, ini adalah Halaman Facebook yang tertaut ke akun Profesional Instagram
Token Akses Halaman yang diminta oleh orang yang bisa melakukan tugas ANALYZE di Halaman
Izin berikut melalui Facebook Login:
- pages_messaging
- pages_read_engagement
- pages_show_list
- read_insights
Akses Lanjutan

Batasan

Agar percakapan baru bisa dihitung, seseorang harus melakukan tindakan, seperti mengirim balasan ke bisnis Anda. Percakapan hanya bisa dilihat orang itu dan tidak dihitung sampai dia melakukan tindakan.

Membaca Metrik Insight

Untuk membaca informasi satu atau beberapa metrik, kirim permintaan GET ke endpoint /PAGE-ID/insights dengan parameter metric yang diatur ke daftar yang dipisahkan koma berisi metrik yang ingin Anda lihat.

Contoh Permintaan

Diformat agar mudah dibaca.

curl -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights
    ?metric=page_messages_new_conversations_unique,page_messages_blocked_conversations_unique 
    &access_token=PAGE-ACCESS-TOKEN"

Setelah berhasil, aplikasi akan menerima tanggapan JSON berikut:

{ 
  "data": [ 
    { 
      "name": "page_messages_new_conversations_unique", 
      "period": "day", 
      "values": [ 
        { 
          "value": "42", 
          "end_time": "1665175977" 
        }, 
      ]
    },
    { 
      "name": "page_messages_blocked_conversations_unique", 
      "period": "day", 
      "values": [ 
        { 
          "value": "0", 
          "end_time": "1665175977" 
        }, 
      ]
    } 
  ],
}

Contoh Permintaan Total Selama Rentang

Contoh berikut menunjukkan jumlah total percakapan unik dan baru selama periode waktu tertentu dengan menyertakan parameter period yang diatur ke total_over_range dengan rentang waktu yang ditentukan oleh parameter since dan until dalam panggilan API kami.

Diformat agar mudah dibaca.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/
    ?metric=page_messages_new_conversations_unique
    &since=UNIX-TIMESTAMP-START
    &until=UNIX-TIMESTAMP-STOP
    &period=total_over_range
    &access_token=PAGE-ACCESS-TOKEN"

Jika berhasil, aplikasi Anda mendapatkan tanggapan JSON berikut dengan jumlah percakapan unik dan baru, serta akhir rentang waktu:

{
  "data": [
    {
      "name": "page_messages_new_conversations_unique",
      "period": "total_over_range",
      "values": [
        {
          "value": 27
          "end_time": "1665175977"
        }
      ],
    }
  ]
}

Contoh Permintaan Perincian

Contoh berikut menunjukkan jumlah total token notifikasi berulang selama periode waktu tertentu dan dikelompokkan berdasarkan topik dan frekuensi.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/
    ?metric=recurring_notifications_tokens   
    &since=UNIX-TIMESTAMP-START
    &until=UNIX-TIMESTAMP-STOP
    &period=total_over_range
    &breakdown=recurring_notifications_topic,recurring_notifications_frequency 
    &access_token=PAGE-ACCESS-TOKEN"

Jika berhasil, aplikasi Anda akan mendapatkan tanggapan JSON berikut dengan token yang dikelompokkan berdasarkan topik "newproducts" dan "10percentsale", dan frekuensi pesan yang tersedia untuk setiap topik "daily", "weekly", dan "monthly" untuk "newproducts" dan "daily" dan "weekly" untuk "10percentsale":

{
  "data": [
    {
      "name": "recurring_notifications_tokens",
      "period": "total_over_range",
      "values": [ 
        {
          "value": 3,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "daily"
        },
        {
          "value": 15,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "weekly"
        },
        {
          "value": 8,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "monthly"
        },
        {
          "value": 17,
          "end_time": "1665175977",
          "recurring_notifications_topic": "10percentsale",
          "recurring_notifications_frequency": "daily"
        },
        {
          "value": 14,
          "end_time": "1665175977",
          "recurring_notifications_topic": "10percentsale",
          "recurring_notifications_frequency": "weekly"
        },
      ]
    }
  ]
}

Parameter Insight

Parameter Deskripsi

breakdown

Dimensi pengelompokan tanggapan. Dapat berupa satu atau beberapa dari berikut ini:

Nama	Deskripsi
`campaign_id`	Melihat data Anda berdasarkan nomor ID kampanye. Contohnya adalah "abc123", "Kampanye pesan musim panas", dan "Obral musim semi 2"
`engagement_source`	Melihat data Anda berdasarkan jenis interaksi dengan notifikasi berulang. Contohnya adalah ID CTA primer dan sekunder (yang CTA-nya diklik)
`message_type`	Melihat data Anda berdasarkan jenis pesan yang dikirim bisnis Anda. Contohnya adalah pesan Marketing
`messaging_channel`	Melihat data Anda berdasarkan saluran yang digunakan untuk mengirimkan pesan kepada pengguna. Contohnya adalah Messenger dan Instagram
`recurring_notifications_entry_point`	Melihat data Anda berdasarkan poin entri ke notifikasi berulang. Contohnya adalah dalam utas, Plugin Obrolan Iklan CTM, plugin Kotak Centang, tautan m.me atau Instagram, dan Halaman Facebook
`recurring_notifications_frequency`	Melihat data Anda berdasarkan frekuensi yang diizinkan oleh ikut serta notifikasi berulang. Contohnya adalah Daily, Weekly, dan Monthly (Harian, Mingguan, dan Bulanan)
`recurring_notifications_topic`	Melihat data Anda berdasarkan topik notifikasi berulang. Contohnya adalah pesan Promosi, peluncuran Produk, dan Promo

date_preset

Rentang tanggal relatif yang bisa digunakan selain since dan until. Dapat berupa last_week, last_month, last_quarter, dan lainnya. Lihat nilai lainnya di panduan Insight Halaman.

metric

Wajib.Daftar metrik yang dipisahkan koma untuk ditampilkan

period

Agregasi yang tersedia dalam rentang since/until atau date_preset. Nilai total_over_range memberikan nilai tunggal untuk metrik selama rentang tanggal tertentu. Dapat berupa day, week, month, days_28, atau total_over_range.

since

Tanggal mulai untuk rentang tanggal yang ingin Anda lihat datanya. Menyertakan data untuk set tanggal mulai pukul 24.00. Format untuk nilainya adalah YYYY-MM-DD. Nilai 2022-01-31 akan memberikan data mulai 31 Januari 2022 pukul 24.00.

until

Tanggal akhir untuk rentang tanggal yang ingin Anda lihat datanya. Tidak menyertakan data untuk set tanggal mulai pukul 24.00. Format untuk nilainya adalah YYYY-MM-DD. Nilai 2022-02-01 akan memberikan data mulai 31 Januari 2022 pukul 23.59.

Metrik yang Tersedia

Metrik berikut tersedia melalui Messaging Insights API:

Nama `metric`	Deskripsi
`page_messages_blocked_conversations_unique`	Jumlah percakapan dengan Halaman yang telah diblokir.
`page_messages_engagement`	Jumlah berapa kali pelanggan berinteraksi dengan pesan marketing yang dikirim Halaman bisnis Anda dengan mengetuk tombol ajakan bertindak. Kemungkinan Nilai `breakdown`: `campaign_id` `engagement_source` `message_type` `messaging_channel` `recurring_notifications_topic` Metrik ini dalam pengembangan.
`page_messages_new_conversations_unique`	Jumlah percakapan pengiriman pesan di Messenger yang dimulai dengan orang yang belum pernah mengirimkan pesan ke bisnis Anda.
`page_messages_order_count`	Berapa kali Anda menghasilkan pesanan di percakapan pengiriman pesan atau di aplikasi atau situs web pihak ketiga yang digunakan untuk mengelola percakapan pengiriman pesan. Metrik ini dalam pengembangan.
`page_messages_paid_order_earnings`	Perkiraan jumlah uang yang Anda hasilkan dari pesanan yang dibuat melalui percakapan pengiriman pesan atau melalui aplikasi atau situs web pihak ketiga yang digunakan untuk mengelola percakapan pengiriman pesan. Pendapatan akhir mungkin berbeda karena konversi mata uang. Metrik ini dalam pengembangan.
`page_messages_read_ratio`	Jumlah pesan marketing yang dibaca dibagi jumlah pesan marketing yang dikirim oleh Halaman Anda. Beberapa pesan yang dibaca mungkin tidak tercatat, seperti jika pelanggan menonaktifkan tanda terima pesan dibaca. Kemungkinan Nilai `breakdown`: `campaign_id` `message_type` `messaging_channel` `recurring_notifications_topic` Metrik ini dalam pengembangan.
`page_messages_reported_conversations_unique`	Jumlah percakapan dari Halaman Anda yang telah dilaporkan oleh orang karena alasan seperti spam, atau berisi konten yang tidak pantas.
`page_messages_sent`	Jumlah pesan marketing yang dikirim oleh Halaman bisnis Anda kepada pelanggan. Kemungkinan Nilai `breakdown`: `campaign_id` `messsage_type` `messaging_channel` `recurring_notifications_topic` Metrik ini sedang dalam pengembangan.
`page_messages_total_messaging_connections`	Jumlah orang yang bisa dikirimi pesan oleh bisnis Anda. Metrik ini menunjukkan jumlah orang yang pernah mengirimkan pesan ke bisnis Anda di Messenger, tidak termasuk orang yang telah memblokir atau melaporkan bisnis Anda di Messenger. Mungkin Anda akan mengalami beberapa batasan atas kemampuan mengirimkan pesan ke koneksi, seperti batasan jumlah pesan yang bisa dikirim selama jangka waktu tertentu. Metrik ini juga hanya menyertakan koneksi yang terjalin sejak Oktober 2016, ketika data tersedia.
`page_messages_with_business_outcomes`	Jumlah koneksi berkirim pesan dengan minimal satu pesanan yang telah dibuat. Metrik ini sedang dalam pengembangan.
`recurring_notifications_tokens`	Berapa kali suatu akun berlangganan untuk menerima pesan marketing dari bisnis Anda. Jika akun telah berlangganan ke beberapa topik, akun akan dihitung lagi untuk setiap topik. Cara menghitungnya: Metrik ini menghitung berapa kali akun setuju untuk menerima pesan berulang dikurangi berapa kali akun berhenti berlangganan. Kemungkinan Nilai `breakdown`: `messaging_channel` `recurring_notifications_frequency` `recurring_notifications_topic` Metrik ini sedang dalam pengembangan.

Pelajari selengkapnya tentang metrik yang sedang dalam pengembangan.

Properti Tanggapan

Informasi berikut bisa ditampilkan dalam panggilan ke Insights API.

Properti	Deskripsi
`data` array objek	Objek daftar metrik
`name` string	Nama metrik
`period` string	Periode waktu selama data dilaporkan
`values` array objek	Daftar data untuk metrik.
`value` int	Jumlah metrik yang diminta selama rentang tanggal tertentu
`end_time` cap waktu unix	Cap waktu UTC dari waktu berakhirnya metrik