Log masukMulakan percubaan percuma
easyCoexistence API rasmi

Webhook Messenger untuk Halaman Facebook: mesej dan peristiwa sebutan

Medan messages bagi webhook Halaman Facebook tercetus apabila seseorang menghantar mesej Messenger kepada Halaman, dan menyampaikan tatasusunan messaging yang mengandungi ID berskop Halaman bagi pengirim, ID Halaman, cap masa serta mid mesej beserta teks atau lampirannya. Medan mention melaporkan sebutan baharu Halaman dalam siaran dan komen, dan Meta menandatangani kedua-duanya dengan X-Hub-Signature-256.

easyCoexistence menghantar mesej dan sebutan Messenger bagi setiap Halaman yang disambungkan ke endpoint HTTPS anda sebaik sahaja tiba, ditandatangani dengan rahsia bagi Halaman itu dan tanpa salinan disimpan, dan send_social_dm membalas dalam tetingkap 24 jam.

5 seconds

Sepantas mana Meta meminta endpoint webhook Messenger membalas setiap pemberitahuan dengan 200 OK.

1 hour

Selepas penghantaran gagal selama tempoh ini, Meta menyahlanggan aplikasi daripada webhook Halaman sehingga ia melanggan semula.

PSID

ID pengirim berskop Halaman dalam peristiwa messages, unik bagi setiap pasangan orang dan Halaman.

Workplace only

Cara rujukan Meta menandakan medan pengirim bagi peristiwa sebutan.

No history

Pemberitahuan webhook terdahulu tidak boleh diambil semula kemudian, jadi penerima perlu menyimpan apa yang diperlukannya.

Apakah yang dihantar medan messages?

Pemberitahuan apabila seseorang menghantar mesej Messenger kepada Halaman. Meta menghantar mesej teks atau mesej berlampiran, yang boleh terdiri daripada imej, audio, video, fail atau pelekat antara jenis lain, dan pautan yang dikongsi boleh tiba sebagai lampiran ganti. Balasan kepada mesej terdahulu membawa reply_to dengan mid mesej tersebut, dan balasan pantas membawa payload-nya.

Bagaimana rupa peristiwa messages?

Tidak seperti perubahan suapan, mesej tiba dalam tatasusunan messaging di dalam entry Halaman. Setiap peristiwa mempunyai sender, iaitu ID berskop Halaman bagi orang itu; recipient, iaitu Halaman; cap masa; dan message, dengan mid dan teks, atau attachments dengan jenis dan URL payload:

A messages event, as Meta sends it
{
  "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!"
          }
        }
      ]
    }
  ]
}

Apakah yang dihantar medan mention?

Perubahan dengan medan mention apabila Halaman disebut dalam siaran atau komen, membawa post_id atau comment_id, mesej, sebarang pautan, foto atau video, serta item dan verb. Meta memberi amaran bahawa sebahagian ID siaran dan komen tersebut tidak boleh diminta, kerana kekurangan kebenaran atau atas sebab privasi, dan rujukannya menandakan medan sender hanya untuk Workplace, jadi sebutan mungkin tiba tanpa pengarangnya.

Medan Messenger manakah yang tidak dihantar?

easyCoexistence melanggan Halaman kepada messages, bukan kepada message_echoes, messaging_postbacks, message_reads atau message_deliveries, jadi mesej yang dihantar oleh Halaman, tekanan butang dan resit baca atau penghantaran tidak dihantar ke hadapan. Balasan yang dihantar dengan send_social_dm mengembalikan ID mesejnya sendiri.

Bagaimana peristiwa sampai ke endpoint anda?

Meta menghantar webhook Halaman kepada aplikasi yang dipasang oleh Halaman, melalui satu URL panggil balik untuk keseluruhan aplikasi. easyCoexistence menyemak X-Hub-Signature-256 Meta pada setiap penghantaran, segera menjawab Meta, dan menghantar setiap entry bagi Halaman yang disambungkan ke endpoint HTTPS yang anda tetapkan untuknya, ditandatangani dengan rahsia Halaman itu sendiri. Tetapkannya dengan set_social_webhook_destination daripada Claude atau ChatGPT, atau dengan PUT /channels/:id/webhook pada Partner API; rahsia dipaparkan sekali sahaja, menetapkannya semula mengeluarkan rahsia baharu, dan URL null mematikan penghantaran ke hadapan.

Bagaimana rupa peristiwa yang diteruskan?

Satu POST yang memuatkan platform, account_id yang diberikan oleh list_social_accounts bagi sambungan Halaman, ID Halaman sebagai external_id, dan entry: entry Meta bagi Halaman itu, tidak diubah. sender.id ialah recipient_id yang diambil oleh send_social_dm untuk balasan dalam tetingkap 24 jam:

A forwarded messages event
{
  "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 anda mengesahkan peristiwa yang diteruskan?

Setiap POST yang diteruskan membawa header X-EC-Signature dalam bentuk t=<unix>,v1=<hex>, dengan v1 ialah HMAC-SHA256 bagi cap masa, titik dan badan mentah, dikunci dengan rahsia penandatanganan Halaman. Kira ia ke atas badan tepat seperti yang diterima, bandingkan dalam masa tetap, dan tolak cap masa yang lebih daripada 5 minit lama.

Node.js: verifying X-EC-Signature
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));
}

Adakah penghantaran dicuba semula?

Tidak oleh easyCoexistence. Setiap entry dihantar ke hadapan sekali sahaja, dalam memori, tanpa salinan disimpan untuk dicuba semula; penghantaran menunggu 8 saat untuk jawapan, tidak mengikut lencongan dan hanya dihantar ke alamat HTTPS yang diselesaikan kepada IP awam. Meta menyatakan bahawa pemberitahuan terdahulu tidak boleh diambil semula kemudian, jadi simpan apa yang anda perlukan semasa ia tiba. Di hulu, Meta mencuba semula penghantaran yang gagal beberapa kali serta-merta, jadi mesej yang sama sekali-sekala boleh sampai dua kali: nyahduplikasi pada mid-nya.

Kesilapan biasa

  • Melakukan kerja sebelum menjawab. Penghantaran ke hadapan tidak dicuba semula, jadi kembalikan 2xx serta-merta dan proses peristiwa kemudian.
  • Mengesahkan tandatangan pada JSON yang telah dihuraikan. Kira HMAC ke atas badan mentah tepat seperti yang tiba.
  • Menganggap mesej sentiasa ada teks. Pelekat, imej atau pautan yang dikongsi tiba sebagai attachments, tanpa medan text.
  • Tidak melakukan nyahduplikasi. Meta boleh menghantar peristiwa semula selepas kegagalan, jadi kunci pada mid mesej sebelum bertindak.
Menggunakan EasyCoexistence untuk ini

Aktifkan penghantaran ke hadapan dengan set_social_webhook_destination atau Partner API. US$ 9 hingga US$ 0.75 setiap sambungan sebulan, berkurang apabila anda menambah sambungan, dengan 3 hari pertama percuma.

Soalan lazim

Medan webhook manakah yang dilanggan easyCoexistence bagi sesebuah Halaman?

messages untuk Messenger dan mention untuk sebutan, di samping feed bagi siaran dan komen Halaman.

Adakah pelekat atau imej Messenger datang dengan teks?

Tidak. Pelekat, imej atau pautan yang dikongsi tiba dalam attachments, setiap satu dengan jenis dan URL payload, dan mesej tidak membawa medan text.

Seberapa pantas endpoint webhook Messenger mesti menjawab?

Dengan 200 OK dalam masa 5 saat. Selepas 1 jam penghantaran gagal, Meta menyahlanggan aplikasi daripada webhook Halaman.

Bagaimana saya membalas mesej yang diteruskan?

Panggil send_social_dm dengan sender.id daripada peristiwa sebagai recipient_id, dalam tempoh 24 jam selepas mesej orang itu.

Teruskan membaca

Sambungkan saluran pertama anda dalam masa dua minit.

Tidak perlu menunggu semakan platform. Sambungkan WhatsApp, Instagram, TikTok atau saluran lain, kemudian minta AI anda menyiarkan, membalas atau melaporkan, dan lihat ia bekerja.

  • 3 hari percuma
  • Batal bila-bila masa
  • API rasmi sahaja
  • Dipantau 24/7

Disahkan pada