Webhook Messenger untuk Halaman Facebook: pesan dan event mention
Field messages pada webhook Halaman Facebook aktif saat seseorang mengirim pesan Messenger ke Halaman. Field ini mengirim array messaging berisi ID pengirim yang khusus Halaman, ID Halaman, stempel waktu, dan mid pesan beserta teks atau lampirannya. Field mention melaporkan mention baru terhadap Halaman di postingan dan komentar. Meta menandatangani keduanya dengan X-Hub-Signature-256.
easyCoexistence meneruskan pesan dan mention Messenger dari setiap Halaman yang terhubung ke endpoint HTTPS Anda saat tiba, ditandatangani dengan rahasia untuk Halaman tersebut tanpa menyimpan salinan, dan send_social_dm membalas dalam jendela 24 jam.
Seberapa cepat Meta meminta endpoint webhook Messenger membalas setiap notifikasi dengan 200 OK.
Setelah pengiriman gagal selama ini, Meta membatalkan langganan aplikasi dari webhook Halaman hingga aplikasi berlangganan lagi.
ID pengirim khusus Halaman dalam event messages, unik untuk setiap pasangan orang dan Halaman.
Cara referensi Meta menandai field sender pada event mention.
Notifikasi webhook sebelumnya tidak bisa diquery nanti, sehingga penerima harus menyimpan apa yang dibutuhkannya.
Apa yang dikirim field messages?
Notifikasi saat seseorang mengirim pesan Messenger ke Halaman. Meta mengirim pesan teks atau pesan dengan lampiran, yang bisa berupa gambar, audio, video, file, atau stiker, dan tipe lain. Tautan yang dibagikan dapat tiba sebagai lampiran acuan cadangan. Balasan atas pesan sebelumnya membawa reply_to dengan mid pesan tersebut, dan balasan cepat membawa payload-nya.
Seperti apa bentuk event messages?
Berbeda dengan perubahan feed, pesan tiba dalam array messaging di dalam entry Halaman. Setiap event memiliki sender, yaitu ID khusus Halaman milik orang tersebut; recipient, yaitu Halaman; timestamp; dan message, dengan mid dan text, atau attachments yang memuat type dan URL payload:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}Apa yang dikirim field mention?
Perubahan dengan field mention saat Halaman di-mention dalam postingan atau komentar, membawa post_id atau comment_id, pesan, tautan, foto, atau video apa pun, serta item dan verb. Meta memperingatkan bahwa sebagian ID postingan dan komentar tersebut tidak bisa diquery, karena tidak ada izin atau demi privasi, dan referensinya menandai field sender hanya untuk Workplace, sehingga mention dapat tiba tanpa penulisnya.
Field Messenger mana yang tidak diteruskan?
easyCoexistence berlangganan Halaman ke messages, bukan ke message_echoes, messaging_postbacks, message_reads, atau message_deliveries, sehingga pesan yang dikirim Halaman, ketukan tombol, dan konfirmasi dibaca atau terkirim tidak diteruskan. Balasan yang dikirim dengan send_social_dm justru mengembalikan ID pesannya sendiri.
Bagaimana event sampai ke endpoint Anda?
Meta mengirim webhook Halaman ke aplikasi yang dipasang Halaman, melalui satu URL callback untuk seluruh aplikasi. easyCoexistence memeriksa X-Hub-Signature-256 Meta pada setiap pengiriman, langsung membalas Meta, dan meneruskan setiap entry untuk Halaman yang terhubung ke endpoint HTTPS yang Anda atur untuknya, ditandatangani dengan rahasia penandatanganan milik Halaman itu sendiri. Atur dengan set_social_webhook_destination dari Claude atau ChatGPT, atau dengan PUT /channels/:id/webhook pada Partner API; rahasia hanya ditampilkan sekali, mengatur ulangnya akan menerbitkan rahasia baru, dan URL null mematikan penerusan.
Seperti apa event yang diteruskan?
Sebuah POST berisi platform, account_id yang diberikan list_social_accounts untuk koneksi Halaman, ID Halaman sebagai external_id, dan entry: entry Meta untuk Halaman tersebut, tanpa diubah. sender.id adalah recipient_id yang diambil send_social_dm untuk balasan dalam jendela layanan pelanggan 24 jam:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}Bagaimana cara memverifikasi event yang diteruskan?
Setiap POST yang diteruskan membawa header X-EC-Signature dalam bentuk t=<unix>,v1=<hex>, dengan v1 adalah HMAC-SHA256 dari stempel waktu, titik, dan body mentah, menggunakan kunci rahasia penandatanganan Halaman. Hitung dari body persis seperti diterima, bandingkan dalam waktu konstan, dan tolak stempel waktu yang lebih dari 5 menit.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}Apakah pengiriman dicoba kembali?
Tidak oleh easyCoexistence. Setiap entry diteruskan sekali, di memori, tanpa salinan untuk dicoba kembali; penerusan menunggu jawaban 8 detik, tidak mengikuti redirect, dan hanya dikirim ke alamat HTTPS yang mengarah ke IP publik. Meta mencatat bahwa notifikasi sebelumnya tidak bisa diquery nanti, jadi simpan apa yang Anda butuhkan saat tiba. Di sisi Meta, pengiriman yang gagal dicoba kembali beberapa kali sekaligus, sehingga pesan yang sama sesekali bisa sampai dua kali: hapus duplikat berdasarkan mid-nya.
Kesalahan umum
- Mengerjakan pekerjaan sebelum membalas. Penerusan tidak mencoba kembali, jadi kembalikan 2xx segera dan proses event setelahnya.
- Memverifikasi tanda tangan pada JSON yang sudah diurai. Hitung HMAC dari body mentah persis seperti diterima.
- Mengira pesan selalu punya teks. Stiker, gambar, atau tautan yang dibagikan datang sebagai attachments, tanpa field text.
- Melewatkan deduplikasi. Meta bisa mengirim event lagi setelah kegagalan, jadi gunakan mid pesan sebagai kunci sebelum bertindak.
Aktifkan penerusan dengan set_social_webhook_destination atau Partner API. US$ 9 hingga US$ 0.75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Field webhook apa saja yang dilangganan easyCoexistence untuk Halaman?
messages untuk Messenger dan mention untuk penyebutan Halaman, di samping feed untuk postingan dan komentar.
Apakah stiker atau gambar Messenger datang dengan teks?
Tidak. Stiker, gambar, atau tautan yang dibagikan datang di attachments, masing-masing dengan type dan URL payload, dan pesan tidak memuat field text.
Seberapa cepat endpoint webhook Messenger harus membalas?
Dengan 200 OK dalam 5 detik. Setelah 1 jam pengiriman gagal, Meta membatalkan langganan aplikasi dari webhook Halaman.
Bagaimana cara membalas pesan yang diteruskan?
Panggil send_social_dm dengan sender.id dari event sebagai recipient_id, dalam 24 jam sejak pesan orang tersebut.
Lanjut membaca
Hubungkan saluran pertama Anda dalam dua menit.
Tanpa menunggu peninjauan platform. Hubungkan WhatsApp, Instagram, TikTok, atau saluran lainnya, lalu minta AI Anda untuk memposting, membalas, atau membuat laporan, dan lihat hasilnya langsung.
- Gratis 3 hari
- Batalkan kapan saja
- Hanya API resmi
- Dipantau 24/7
Diverifikasi pada