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:
Sebelum memulai, kami berasumsi Anda telah:
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.
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.
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.
Endpoint Anda harus menanggapi semua notifikasi:
200 OK HTTPS
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); } });
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:
GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444
Saat endpoint menerima permintaan verifikasi, endpoint itu harus:
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).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); } } });
Parameter | Contoh Nilai | Deskripsi |
---|---|---|
|
| Nilai ini akan selalu diatur ke |
|
|
|
|
| String yang kami dapatkan dari kolom Verifikasikan Token di Dasbor Aplikasi pada aplikasi. Anda akan mengatur string ini setelah Anda menyelesaikan langkah pengaturan konfigurasi Webhooks. |
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.
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>"
},
...
}
]
}
]
}
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.
Kami tidak menyimpan data notifikasi peristiwa Webhooks yang kami kirimkan kepada Anda, jadi pastikan Anda merekam dan menyimpan konten payload yang ingin Anda pertahankan.
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:
X-Hub-Signature-256
(apa pun setelah sha256=
). Jika tanda tangannya cocok, berarti muatan tersebut asli.Harap diperhatikan bahwa kami membuat tanda tangan menggunakan payload versi escaped unicode, dengan enam digit berhuruf kecil. Jika Anda hanya menghitung berdasarkan bita yang didekode, Anda akan menghasilkan tanda tangan yang berbeda. Contoh: string äöå
harus dilepas ke \u00e4\u00f6\u00e5
.
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."); } } }
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.
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.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.
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.
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
.
Peristiwa Webhook | Keterangan |
---|---|
| Berlangganan peristiwa Pesan Diterima |
| Berlangganan peristiwa Penautan Akun |
| Berlangganan peristiwa Update Proses Pembayaran |
| Berlangganan peristiwa Pesan Terkirim |
| Berlangganan peristiwa Pesan Echo |
| Berlangganan ke peristiwa Game Instan |
| Berlangganan ke peristiwa Protokol Handover |
| Berlangganan peristiwa Pilihan Menerima Plugin |
| Berlangganan peristiwa Pembayaran |
| Berlangganan ke peristiwa Penegakan Kebijakan |
| Berlangganan peristiwa Kiriman Ulang Diterima |
| Berlangganan ke peristiwa Sebelum Proses Pembayaran |
| Berlangganan peristiwa Pesan Dibaca |
| Berlangganan peristiwa Referal |
| Berlangganan ke peristiwa Saluran Siaga Protokol Handover |
Anda harus menghubungkan aplikasi Webhooks Anda ke Halaman Anda dan berlangganan Halaman Anda ke notifikasi Webhooks yang ingin Anda terima.
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.
Halaman Anda harus berlangganan notifikasi Webhooks yang ingin Anda terima.
MODERATE
di Halaman yang sedang di-kueri
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"
{ "success": "true" }
Untuk melihat aplikasi mana yang telah diinstal Halaman Anda, kirim permintaan GET
:
curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps &access_token=PAGE-ACCESS-TOKEN"
{ "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.
Anda juga dapat menggunakan Graph API Explorer untuk mengirim permintaan Halaman Anda agar berlangganan kolom Webhooks.
pages_manage_metadata
. Ini akan menukar token aplikasi Anda dengan token akses pengguna dengan izin pages_manage_metadata
yang diberikan.GET
dan memilih POST
.me?fields=id,name
default dengan id Halaman diikuti dengan /subscribed_apps
, lalu kirimkan kueri. 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.