Messenger webhook'u Facebook Sayfaları için: mesajlar ve bahsetme olayları
Facebook'un Sayfa webhook'larının messages alanı, bir kişi Sayfaya Messenger mesajı gönderdiğinde tetiklenir. Bu alan, Sayfaya özgü gönderen kimliği, Sayfanın kimliği, bir zaman damgası ve mesajın mid değeriyle birlikte metnini veya eklerini içeren bir messaging dizisi iletir. mention alanı, gönderilerde ve yorumlarda Sayfanın yeni bahsetmelerini bildirir. Meta her iki bildirimi de X-Hub-Signature-256 ile imzalar.
easyCoexistence, bağlı her Sayfanın Messenger mesajlarını ve bahsetmelerini geldikçe HTTPS uç noktanıza iletir.
Meta'nın, bir Messenger webhook uç noktasının her bildirime 200 OK ile ne kadar hızlı yanıt vermesini istediği.
Teslimatlar bu süre boyunca başarısız olursa Meta, yeniden abone olunana kadar uygulamayı Sayfanın webhook aboneliklerinden çıkarır.
Bir messages olayındaki, her kişi ve Sayfa çifti için benzersiz olan gönderenin Sayfaya özgü kimliği.
Meta'nın referansının bir mention olayındaki sender alanını nasıl işaretlediği.
Geçmiş webhook bildirimleri daha sonra sorgulanamaz; bu yüzden alıcının ihtiyaç duyduğu veriyi saklaması gerekir.
messages alanı neyi gönderir?
Bir kişi Sayfaya Messenger mesajı gönderdiğinde gelen bildirim. Meta metin mesajlarını veya görsel, ses, video, dosya ya da çıkartma gibi türlerde eklerle birlikte gelen mesajları iletir; paylaşılan bir bağlantı yedek ek olarak gelebilir. Önceki bir mesaja verilen yanıt, o mesajın mid değerini taşıyan reply_to alanını, hızlı yanıt ise payload değerini taşır.
messages olayı nasıl görünür?
Gönderi değişikliklerinin aksine, mesaj Sayfanın entry alanının içinde bir messaging dizisiyle gelir. Her olayda sender, kişinin Sayfaya özgü kimliği; recipient, Sayfa; bir zaman damgası; ve mid değeri ile metni ya da türü ve payload URL'si olan ekleri bulunan message yer alır:
{
"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!"
}
}
]
}
]
}mention alanı neyi gönderir?
Sayfa bir gönderide veya yorumda anıldığında, post_id veya comment_id, mesaj, varsa bağlantı, fotoğraf ya da video ile item ve verb alanlarını taşıyan, field değeri mention olan bir değişiklik. Meta, bazı gönderi ve yorum kimliklerinin izin eksikliği veya gizlilik nedeniyle sorgulanamayacağını uyarır. Referansı da sender alanını yalnızca Workplace için işaretler, bu yüzden bir bahsetme yazarı olmadan gelebilir.
Hangi Messenger alanları iletilmez?
easyCoexistence, Sayfaları yalnızca messages alanına abone eder; message_echoes, messaging_postbacks, message_reads veya message_deliveries alanlarına değil. Bu nedenle Sayfanın gönderdiği mesajlar, düğme tıklamaları ile okundu ve teslim alındı bilgileri iletilmez. send_social_dm ile gönderilen bir yanıt, bunun yerine kendi mesaj kimliğini döndürür.
Olaylar uç noktanıza nasıl ulaşır?
Meta, Sayfa webhook'larını Sayfanın kurduğu uygulamaya, uygulamanın tamamı için tek bir geri çağırma URL'si üzerinden iletir. easyCoexistence her teslimatta Meta'nın X-Hub-Signature-256 imzasını doğrular, Meta'ya hemen yanıt verir ve bağlı her Sayfanın girişini, o Sayfaya ait gizli anahtarla imzalanmış olarak, sizin ayarladığınız HTTPS uç noktasına iletir. Bunu Claude veya ChatGPT'den set_social_webhook_destination ile ya da Partner API'de PUT /channels/:id/webhook ile ayarlayın. Gizli anahtar yalnızca bir kez gösterilir, yeniden ayarlamak yeni bir anahtar üretir ve null URL iletimi kapatır.
İletilen bir olay nasıl görünür?
Platformu, Sayfa bağlantısına ait account_id değerini (list_social_accounts ile alınır), Sayfanın kimliğini external_id olarak ve Sayfa için Meta'nın entry verisini değiştirilmeden taşıyan bir POST. sender.id, 24 saatlik pencere içinde yanıt için send_social_dm ile recipient_id olarak kullanılan değerdir:
{
"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>" }
}
]
}
}İletilen bir olayı nasıl doğrularsınız?
İletilen her POST, t=<unix>,v1=<hex> biçiminde bir X-EC-Signature başlığı taşır. Burada v1, zaman damgası, bir nokta ve ham gövdenin HMAC-SHA256 değeridir ve Sayfanın imzalama anahtarıyla hesaplanır. Gövdeyi alındığı gibi, tam olarak hesaplayın, sabit süreli karşılaştırın ve 5 dakikadan eski bir zaman damgasını reddedin.
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));
}İletilen bir teslimat yeniden denenir mi?
easyCoexistence tarafından hayır. Her giriş yalnızca bir kez, bellekte iletilir; yeniden denemek için bir kopyası tutulmaz. İletim yanıt için 8 saniye bekler, yönlendirmeleri takip etmez ve yalnızca genel bir IP'ye çözümlenen HTTPS adresine gider. Meta, geçmiş bildirimlerin daha sonra sorgulanamayacağını belirtir; bu yüzden gelenleri ihtiyacınız olduğu kadar saklayın. Meta tarafında ise başarısız bir teslimat birkaç kez hemen yeniden denenir. Bu nedenle aynı mesaj nadiren iki kez ulaşabilir; mid değerine göre tekilleştirin.
Yaygın hatalar
- Yanıt vermeden önce işi yapmak. İletim yeniden denenmez; bu yüzden hemen 2xx dönün ve olayı sonra işleyin.
- İmzayı ayrıştırılmış JSON üzerinde doğrulamak. HMAC'i, geldiği gibi ham gövde üzerinden hesaplayın.
- Her mesajın metni olduğunu varsaymak. Çıkartma, görsel veya paylaşılan bir bağlantı eklerle gelir ve metin alanı yoktur.
- Tekilleştirmeyi atlamak. Meta, bir hatadan sonra bir olayı yeniden teslim edebilir; bu nedenle işlemeden önce mid değerini anahtar olarak kullanın.
Her Sayfaya özgü bir anahtarla imzalanır ve hiçbir kopya tutulmaz. send_social_dm ile 24 saatlik pencere içinde yanıt verirsiniz. İletimi set_social_webhook_destination ile veya Partner API üzerinden açın. Bağlantı başına aylık US$ 9 ile US$ 0.75 arasında, bağlantı ekledikçe düşer; ilk 3 gün ücretsiz deneme.
Sık sorulan sorular
easyCoexistence bir Sayfayı hangi webhook alanlarına abone eder?
Messenger için messages, bahsetmeler için mention ve Sayfanın gönderileri ile yorumları için feed.
Messenger çıkartması veya görseli metinle gelir mi?
Hayır. Çıkartma, görsel veya paylaşılan bir bağlantı eklerde gelir; her biri bir tür ve bir payload URL'si taşır ve mesajda metin alanı bulunmaz.
Bir Messenger webhook uç noktası ne kadar sürede yanıt vermelidir?
5 saniye içinde 200 OK ile. 1 saat boyunca başarısız teslimat olursa Meta, uygulamanın Sayfa webhook aboneliğini kaldırır.
İletilen bir mesaja nasıl yanıt veririm?
Olaydaki sender.id değerini recipient_id olarak send_social_dm ile, kişinin mesajından itibaren 24 saat içinde çağırın.
Okumaya devam edin
İlk kanalınızı iki dakikada bağlayın.
Beklemeniz gereken platform incelemesi yok. WhatsApp, Instagram, TikTok veya başka bir kanalı bağlayın, ardından yapay zekânızdan paylaşım yapmasını, yanıtlamasını ya da rapor vermesini isteyin ve işini izleyin.
- 3 gün ücretsiz
- İstediğiniz zaman iptal
- Yalnızca resmi API'ler
- 7/24 izleniyor
Doğrulama tarihi