Webhooks Meta untuk Platform Messenger

Webhooks Meta memungkinkan Anda menerima notifikasi HTTP realtime tentang perubahan objek tertentu di grafik sosial Meta. Contoh: kami bisa mengirimi Anda notifikasi saat seseorang mengirimkan pesan ke Halaman Facebook atau akun Profesional Instagram Anda. Notifikasi Webhooks memungkinkan Anda untuk melacak pesan masuk dan pembaruan status pesan. Notifikasi Webhooks juga memungkinkan Anda untuk menghindari batas laju yang akan terjadi jika Anda meng-kueri endpoint Platform Messenger untuk melacak perubahan ini.

Agar berhasil menerapkan Webhooks untuk percakapan Messenger atau Instagram, Anda akan perlu:

1. Membuat endpoint pada server Anda untuk menerima dan memproses notifikasi Webhooks Anda: objek JSON
2. Mengonfigurasi produk Webhooks Meta di Dasbor Aplikasi Anda
3. Berlangganan notifikasi Webhooks Meta yang ingin Anda terima
4. Instal aplikasi berkirim pesan Anda di Halaman Facebook yang tertaut ke bisnis Anda atau akun Profesional Instagram Anda

Sebelum Memulai

Sebelum memulai, kami berasumsi Anda telah:

• Membaca dan menerapkan komponen yang diperlukan untuk pengembangan dengan Meta di Ringkasan Platform Messenger

Mengonfigurasi Server Node.JS Anda

Server Anda harus dapat memproses dua jenis permintaan HTTPS: Permintaan Verifikasi dan Notifikasi Peristiwa. Karena kedua permintaan ini menggunakan HTTPS, server harus memiliki TLS yang valid atau sertifikat SSL yang secara tepat dikonfigurasi dan diinstal. Sertifikat bertanda tangan mandiri tidak didukung.

Bagian di bawah menjelaskan akan seperti apa di tiap permintaan dan cara menanggapinya.

Contoh kode yang ditampilkan di sini diambil dari contoh aplikasi kami di GitHub . Kunjungi Github untuk melihat contoh lengkap dan informasi selengkapnya tentang pengaturan server Webhooks Anda.

Membuat Endpoint

Untuk membuat endpoint guna menerima notifikasi Webhooks dari Platform Messenger, file app.js mungkin terlihat seperti berikut:

// Create the endpoint for your webhook

app.post("/webhook", (req, res) => {
  let body = req.body;

  console.log(`\u{1F7EA} Received webhook:`);
  console.dir(body, { depth: null });
    
...
   

Kode ini membuat endpoint /webhook yang menerima permintaan POST dan memeriksa bahwa permintaan itu adalah notifikasi Webhooks.

Memberikan tanggapan 200 OK

Endpoint harus memberikan tanggapan 200 OK, yang memberi tahu Platform Messenger bahwa peristiwa telah diterima dan tidak perlu dikirim ulang. Biasanya, Anda tidak akan mengirim tanggapan ini sampai Anda selesai memproses notifikasi.

Menanggapi Notifikasi Peristiwa

Endpoint Anda harus menanggapi semua notifikasi:

• dengan tanggapan 200 OK HTTPS
• dalam 5 detik atau kurang

Kode berikut ada dalam app.post di file app.js Anda dan mungkin terlihat sebagai berikut:

...
  // Send a 200 OK response if this is a page webhook

  if (body.object === "page") {
    // Returns a '200 OK' response to all requests
    res.status(200).send("EVENT_RECEIVED");
...
    // Determine which webhooks were triggered and get sender PSIDs and locale, message content and more.
...
  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
}); 

Permintaan Verifikasi

Saat Anda mengonfigurasi produk Webhooks di Dasbor Aplikasi di aplikasi Anda, kami akan mengirimkan permintaan GET ke URL endpoint Anda. Verifikasi permintaan akan menyertakan parameter string kueri berikut, yang ditambahkan ke akhir URL endpoint Anda. Hasilnya akan seperti ini:

Contoh Permintaan Verifikasi

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444

Memvalidasi Permintaan Verifikasi

Saat endpoint menerima permintaan verifikasi, endpoint itu harus:

• Memverifikasi bahwa nilai hub.verify_token cocok dengan string yang Anda atur Verifikasikan Token saat Anda mengonfigurasi produk Webhooks di Dasbor Aplikasi (Anda belum menyiapkan string token ini).
• Menanggapi dengan nilai hub.challenge.

File app.js mungkin terlihat seperti berikut ini:

// Add support for GET requests to our webhook
app.get("/messaging-webhook", (req, res) => {
  
// Parse the query params
  let mode = req.query["hub.mode"];
  let token = req.query["hub.verify_token"];
  let challenge = req.query["hub.challenge"];

  // Check if a token and mode is in the query string of the request
  if (mode && token) {
    // Check the mode and token sent is correct
    if (mode === "subscribe" && token === config.verifyToken) {
      // Respond with the challenge token from the request
      console.log("WEBHOOK_VERIFIED");
      res.status(200).send(challenge);
    } else {
      // Respond with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
});

Catatan:PHP mengubah titik (.) ke garis bawah (_) dalam nama parameter .

Jika Anda membuka Dasbor Aplikasi dan mengonfigurasi produk Webhooks (dengan demikian memicu Permintaan Verifikasi), dasbor akan menunjukkan apakah endpoint memvalidasi permintaan dengan benar. Jika Anda menggunakan endpoint //app/subscriptions Graph API untuk mengonfigurasi produk Webhooks, API akan menanggapi dengan berhasil atau gagal.

Notifikasi Peristiwa

Saat Anda mengonfigurasi produk Webhooks, Anda akan berlangganan ke fields spesifik pada jenis object (misalnya: kolom messages pada objek page). Saat ada perubahan ke salah satu kolom ini, kami akan mengirimkan endpoint Anda permintaan POST dengan muatan JSON yang menjelaskan perubahan tersebut.

Contoh: jika Anda berlangganan kolom message_reactions objek page dan salah satu pelanggan menanggapi pesan yang dikirimkan aplikasi Anda, kami akan mengirimi Anda permintaan POST yang akan terlihat seperti ini:

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },

          ...
        }
      ]
    }
  ]
}

Konten Muatan

Payload akan berisi objek yang menjelaskan perubahan. Saat mengonfigurasi produk Webhooks, Anda dapat menandakan apakah payload harus hanya berisi nama kolom yang diubah, atau juga harus menyertakan nilai baru.

Kami memformat semua payload dengan JSON, sehingga Anda dapat mem-parse payload menggunakan metode atau paket parsing JSON umum.

Memvalidasi Payload

Kami menandatangani semua payload Notifikasi Peristiwa dengan tanda tangan SHA256 dan memasukkan tanda tangan dalam header 'X-Hub-Signature-256' permintaan, didahului dengan 'sha256='. Anda tidak harus memvalidasi payload, tetapi sebaiknya Anda melakukannya dan kami sangat merekomendasikan hal ini.

Untuk memvalidasi muatan:

1. Buat tanda tangan SHA256 menggunakan muatan dan Rahasia Aplikasi aplikasi Anda.
2. Bandingkan tanda tangan tersebut dengan tanda tangan di header X-Hub-Signature-256 (apa pun setelah sha256=). Jika tanda tangannya cocok, berarti muatan tersebut asli.

File app.js mungkin terlihat seperti berikut ini:

// Import dependencies and set up http server
const express = require("express"),
  bodyParser = require("body-parser"),
  { urlencoded, json } = require("body-parser"),
  app = express().use(bodyParser.json());
    
    ...


// Verify that the callback came from Facebook.
function verifyRequestSignature(req, res, buf) {
  var signature = req.headers["x-hub-signature-256"];

  if (!signature) {
    console.warn(`Couldn't find "x-hub-signature-256" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.appSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Couldn't validate the request signature.");
    }
  }
}

Coba Ulang Penyampaian Webhooks

Jika notifikasi yang dikirimkan ke server Anda gagal, kami akan segera mencoba beberapa kali lagi. Server Anda harus menangani deduplikasi dalam kasus ini. Jika, setelah 15 menit, notifikasi masih tidak dapat tersampaikan, pemberitahuan akan dikirimkan ke akun developer Anda.

Jika penyampaian notifikasi terus gagal selama 1 jam, Anda akan menerima pemberitahuan Webhooks Dinonaktifkan, dan aplikasi Anda akan berhenti berlangganan Webhooks untuk Halaman atau akun Profesional Instagram tersebut. Setelah Anda menyelesaikan masalah, Anda harus berlangganan Webhooks lagi.

Menguji Webhooks Anda

Untuk menguji verifikasi Webhooks Anda, jalankan permintaan cURL berikut dengan token verifikasi Anda:

curl -X GET "localhost:1337/webhook?hub.verify_token=YOUR-VERIFY-TOKEN&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

Jika verifikasi Webhooks Anda berfungsi sesuai harapan, maka Anda akan melihat ini:

• WEBHOOK_VERIFIED tercantum di baris perintah tempat proses node Anda berjalan.
• CHALLENGE_ACCEPTED tercantum di baris perintah tempat Anda mengirimkan permintaan cURL.

Untuk menguji Webhooks Anda, kirimkan permintaan cURL berikut:

curl -H "Content-Type: application/json" -X POST "localhost:1337/webhook" -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

Jika Webhooks Anda berfungsi sesuai harapan, maka Anda akan melihat ini:

• TEST_MESSAGE tercantum di baris perintah tempat proses node Anda berjalan.
• EVENT RECEIVED tercantum di baris perintah tempat Anda mengirimkan permintaan cURL.

Berlangganan Webhooks Meta

Setelah endpoint server Webhooks atau aplikasi contoh Anda siap, buka Dasbor Aplikasi untuk berlangganan Webhooks Meta.

Dalam contoh ini, kami akan menggunakan dasbor untuk mengonfigurasi Webhooks dan berlangganan kolom messages. Setiap kali pelanggan mengirim pesan ke aplikasi Anda, notifikasi akan dikirim ke endpoint Webhooks Anda.

1. Di Dasbor Aplikasi, buka Produk > Messenger > Pengaturan.
   • Beberapa Webhooks Platform Messenger tidak tersedia untuk berkirim pesan di Instagram. Jika Anda hanya menerapkan Webhooks untuk Instagram dan mengetahui Webhooks yang tersedia untuk berkirim pesan di Instagram, Anda dapat berlangganan Webhooks di sini. Untuk hanya melihat dan berlangganan Webhooks untuk berkirim pesan di Instagram, Anda dapat membuka pengaturan Instagram.

2. Masukkan URL endpoint Anda di kolom URL Panggilan Balik dan tambahkan token verifikasi Anda ke kolom Verifikasikan Token. Kami akan menyertakan string ini di semua Permintaan Verifikasi. Jika Anda menggunakan salah satu aplikasi contoh kami, ini harus berupa string sama yang Anda gunakan untuk variabel konfigurasi TOKEN Anda.

3. Berlangganan kolom yang Anda ingin dikirimi notifikasi dan klik Simpan.

4. Langkah terakhir adalah berlangganan ke setiap kolom. Segera berlangganan kolom messages dan kirimkan Notifikasi Peristiwa.

   Jika dikonfigurasi secara tepat, endpoint akan memvalidasi muatan dan mengeksekusi kode apa pun yang sudah Anda siapkan saat validasi berhasil. Jika Anda menggunakan aplikasi contoh kami, muat URL aplikasi di browser web. Konten payload seharusnya ditampilkan.

Anda dapat mengubah langganan Webhooks Anda, memverifikasi token, atau versi API kapan saja menggunakan Dasbor Aplikasi.

Catatan: Anda direkomendasikan agar menggunakan versi API terbaru untuk menerima semua informasi yang tersedia untuk setiap Webhooks.

Anda juga dapat melakukan ini secara terprogram dengan menggunakan endpoint /app/subscriptions.

Kolom Platform Messenger yang Tersedia

Menghubungkan Aplikasi Anda

Anda harus menghubungkan aplikasi Webhooks Anda ke Halaman Anda dan berlangganan Halaman Anda ke notifikasi Webhooks yang ingin Anda terima.

Menambahkan Aplikasi

Anda dapat menghubungkan aplikasi ke Halaman di Meta Business Suite > Semua Fitur > Aplikasi Bisnis

Catatan: Anda harus berlangganan semua aplikasi berkirim pesan untuk bisnis Anda ke Webhooks berkirim pesan.

Langganan untuk Halaman Anda

Halaman Anda harus berlangganan notifikasi Webhooks yang ingin Anda terima.

Persyaratan

• Token akses Halaman yang diminta dari orang yang dapat melakukan tugas MODERATE di Halaman yang sedang di-kueri
• Izin pages_messaging dan pages_manage_metadata

Untuk berlangganan kolom Webhooks, kirim permintaan POST ke edge subscribed_apps Halaman menggunakan token akses Halaman.

curl -i -X POST "https://graph.facebook.com/PAGE-ID/subscribed_apps
  ?subscribed_fields=messages
  &access_token=PAGE-ACCESS-TOKEN"

Contoh Tanggapan

{
  "success": "true"
}

Untuk melihat aplikasi mana yang telah diinstal Halaman Anda, kirim permintaan GET:

Contoh Permintaan

curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps
  &access_token=PAGE-ACCESS-TOKEN"

Contoh Tanggapan

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "APP-ID"
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

Jika Halaman Anda belum menginstal aplikasi apa pun, API akan menampilkan set data kosong.

Graph API Explorer

Anda juga dapat menggunakan Graph API Explorer untuk mengirim permintaan Halaman Anda agar berlangganan kolom Webhooks.

1. Pilih aplikasi Anda di menu pilihan Aplikasi.
2. Klik Dapatkan Token dan pilih Dapatkan Token Akses Pengguna, lalu pilih izin pages_manage_metadata. Ini akan menukar token aplikasi Anda dengan token akses pengguna dengan izin pages_manage_metadata yang diberikan.
3. Klik Dapatkan Token lagi dan pilih Halaman Anda. Ini akan menukar token akses Pengguna Anda dengan token akses Halaman.
4. Ubah metode operasi dengan mengeklik menu pilihan GET dan memilih POST.
5. Ganti kueri me?fields=id,name default dengan id Halaman diikuti dengan /subscribed_apps, lalu kirimkan kueri.

Persyaratan Akses

Untuk menerima notifikasi dari orang-orang yang memiliki peran di aplikasi Anda, seperti admin aplikasi, developer, atau penguji, aplikasi Anda hanya membutuhkan Akses Standar. Untuk menerima notifikasi dari pelanggan Anda, orang-orang yang tidak memiliki peran di aplikasi Anda, aplikasi Anda akan membutuhkan Advanced Access.

Pelajari selengkapnya tentang <Akses Standar dan Advanced Access <, data dapat diakses dengan masing-masing akses, dan persyaratan penerapan.

Langkah Berikutnya

Ikuti tur contoh aplikasi kami – Unduh kode untuk contoh aplikasi kami untuk mempelajari selengkapnya tentang fitur yang ditawarkan Platform Messenger.

Lihat Juga

• Pelajari cara mendapatkan notifikasi ketika percakapan diteruskan dari satu aplikasi ke aplikasi lain menggunakan Protokol Serah Terima Messenger
• Pelajari selengkapnya tentang Webhooks Meta untuk Graph API