Webhooks ของ Meta สำหรับแพลตฟอร์ม Messenger

Webhooks ของ Meta ช่วยให้คุณได้รับการแจ้งเตือน HTTP แบบเรียลไทม์เกี่ยวกับการเปลี่ยนแปลงอ็อบเจ็กต์บางรายการในกราฟสังคมของ Meta ตัวอย่างเช่น เราสามารถส่งการแจ้งเตือนถึงคุณเมื่อมีผู้ใช้ส่งข้อความถึงเพจ Facebook หรือบัญชีมืออาชีพบน Instagram ของคุณ การแจ้งเตือน Webhooks ช่วยให้คุณสามารถติดตามข้อความที่เข้ามาและการอัพเดตสถานะของข้อความได้ ซึ่งการแจ้งเตือน Webhooks ช่วยให้คุณสามารถหลีกเลี่ยงขีดจำกัดอัตราที่จะเกิดขึ้นหากคุณสืบค้นตำแหน่งข้อมูลของแพลตฟอร์ม Messenger เพื่อติดตามการเปลี่ยนแปลงเหล่านี้

หากต้องการใช้ Webhooks สำหรับการสนทนาใน Messenger หรือ Instagram ได้อย่างประสบความสำเร็จ คุณจะต้องดำเนินการดังนี้

1. สร้างตำแหน่งข้อมูลบนเซิร์ฟเวอร์ของคุณเพื่อรับและประมวลผลการแจ้งเตือน Webhooks ซึ่งเป็นอ็อบเจ็กต์ JSON
2. กำหนดค่าผลิตภัณฑ์ Webhooks ของ Meta ในแดชบอร์ดของแอพของคุณ
3. สมัครรับข้อมูลการแจ้งเตือน Webhooks ของ Meta ที่คุณต้องการ
4. ติดตั้งแอพส่งข้อความของคุณบนเพจ Facebook ที่เชื่อมโยงกับธุรกิจหรือบัญชีมืออาชีพบน Instagram ของคุณ

ก่อนเริ่มต้น

ก่อนเริ่มต้น เราถือว่าคุณได้ทำสิ่งต่อไปนี้แล้ว

• ศึกษาและปรับใช้องค์ประกอบต่างๆ ที่จำเป็นสำหรับการพัฒนาโดยใช้ Meta ที่ระบุอยู่ในภาพรวมเกี่ยวกับแพลตฟอร์ม Messenger

กำหนดค่าเซิร์ฟเวอร์ Node.JS ของคุณ

เซิร์ฟเวอร์ของคุณต้องสามารถประมวลคำขอ HTTPS ได้ 2 ประเภท ได้แก่ คำขอให้ตรวจสอบยืนยันและการแจ้งเตือนเหตุการณ์ เนื่องจากคำขอทั้ง 2 ประเภทนี้ใช้ HTTPS เซิร์ฟเวอร์ของคุณจึงต้องมีการกำหนดค่าและติดตั้งใบรับรอง TLS หรือ SSL ที่ใช้งานได้ไว้อย่างถูกต้อง โดยระบบจะไม่รองรับใบรับรองที่ลงนามเอง

ส่วนด้านล่างนี้จะอธิบายสิ่งที่จะอยู่ในคำขอแต่ละประเภทและวิธีตอบกลับคำขอเหล่านั้น

ตัวอย่างโค้ดที่แสดงในที่นี้นำมาจากแอพตัวอย่างที่อยู่ใน GitHub โปรดไปที่ GitHub เพื่อดูตัวอย่างที่ครบถ้วนสมบูรณ์และข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่าเซิร์ฟเวอร์ Webhooks ของคุณ

สร้างตำแหน่งข้อมูล

หากต้องการสร้างตำแหน่งข้อมูลเพื่อรับการแจ้งเตือน Webhooks จากแพลตฟอร์ม Messenger ไฟล์ app.js อาจมีลักษณะดังนี้

// 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 });
    
...
   

โค้ดนี้จะสร้างตำแหน่งข้อมูล /webhook ที่ยอมรับคำขอ POST และตรวจสอบว่าคำขอนั้นเป็นการแจ้งเตือนจาก Webhook

ส่งคืนการตอบกลับเป็น 200 OK

ตำแหน่งข้อมูลนี้ต้องส่งคืนการตอบกลับเป็น 200OK ที่จะบอกแพลตฟอร์ม Messenger ว่าได้รับเหตุการณ์แล้วและไม่จำเป็นต้องส่งซ้ำ ซึ่งโดยปกติ คุณจะไม่ส่งการตอบกลับนี้จนกว่าการประมวลผลการแจ้งเตือนเสร็จสิ้นแล้ว

การตอบกลับการแจ้งเตือนเหตุการณ์

ตำแหน่งข้อมูลของคุณควรตอบกลับการแจ้งเตือนทั้งหมด:

• ด้วยการตอบกลับ 200 OK HTTPS
• ภายใน 5 วินาที หรือน้อยกว่านั้น

โค้ดต่อไปนี้จะอยู่ใน app.post ในไฟล์ app.js ของคุณ และอาจมีลักษณะดังนี้

...
  // 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);
  }
}); 

คำขอให้ตรวจสอบยืนยัน

ทุกครั้งที่คุณกำหนดค่าผลิตภัณฑ์ Webhooks ในแดชบอร์ดของแอพ เราจะส่งคำขอ GET ไปที่ URL ตำแหน่งข้อมูลของคุณ คำขอให้ตรวจสอบยืนยันจะมีพารามิเตอร์สตริงสืบค้นต่อไปนี้ ซึ่งอยู่ต่อท้าย URL ตำแหน่งข้อมูลของคุณ โดยจะมีลักษณะดังนี้

ตัวอย่างคำขอให้ตรวจสอบยืนยัน

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

การตรวจสอบความถูกต้องของคำขอให้ตรวจสอบยืนยัน

ตำแหน่งข้อมูลของคุณต้องดำเนินการต่อไปนี้ เมื่อใดก็ตามที่ได้รับคำขอให้ตรวจสอบยืนยัน

• ตรวจสอบยืนยันว่าค่า hub.verify_token ตรงกับสตริงที่คุณตั้งค่าไว้ในช่อง "โทเค็นการตรวจสอบยืนยัน" เมื่อคุณกำหนดค่าผลิตภัณฑ์ Webhooks ในแดชบอร์ดของแอพ (คุณยังไม่ได้ตั้งค่าสตริงโทเค็นนี้)
• ตอบกลับด้วยค่า hub.challenge

ไฟล์ app.js ของคุณอาจมีลักษณะดังนี้

// 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);
    }
  }
});

หมายเหตุ: PHP จะแปลงจุด (.) เป็นขีดล่าง (_) ในชื่อพารามิเตอร์

หากคุณอยู่ในแดชบอร์ดของแอพและกำลังกำหนดค่าผลิตภัณฑ์ Webhooks ของคุณ (และทริกเกอร์คำขอให้ตรวจสอบยืนยัน) แดชบอร์ดจะระบุว่าตำแหน่งข้อมูลของคุณตรวจสอบคำขออย่างถูกต้องหรือไม่ API จะตอบกลับเพื่อระบุว่าสำเร็จหรือล้มเหลว หากคุณใช้ตำแหน่งข้อมูล /app/subscriptions ของ API กราฟเพื่อกำหนดค่าผลิตภัณฑ์ Webhooks

การแจ้งเตือนเหตุการณ์

เมื่อคุณกำหนดค่าผลิตภัณฑ์ Webhooks คุณจะต้องสมัครรับข้อมูลจาก fields ที่เฉพาะเจาะจงในประเภท object (เช่น ช่อง messages บนอ็อบเจ็กต์ page) เมื่อใดก็ตามที่มีการเปลี่ยนแปลงในช่องใดช่องหนึ่ง เราจะส่งคำขอ POST ไปที่ตำแหน่งข้อมูลของคุณโดยมีเพย์โหลด JSON ที่อธิบายการเปลี่ยนแปลงดังกล่าว

ตัวอย่างเช่น หากคุณสมัครรับข้อมูลจากช่อง message_reactions ของอ็อบเจ็กต์ page และลูกค้าได้แสดงความรู้สึกกับข้อความที่แอพของคุณส่ง เราจะส่งคำขอ POST ให้คุณซึ่งจะมีลักษณะดังนี้

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

          ...
        }
      ]
    }
  ]
}

เนื้อหาเพย์โหลด

เพย์โหลดจะมีอ็อบเจ็กต์ที่อธิบายการเปลี่ยนแปลง เมื่อคุณกำหนดค่าผลิตภัณฑ์ Webhooks คุณจะสามารถระบุได้ว่าเพย์โหลดควรมีเฉพาะชื่อของช่องที่เปลี่ยนแปลงหรือไม่ หรือเพย์โหลดควรรวมค่าใหม่ไว้ด้วยหรือไม่

เราจัดรูปแบบเพย์โหลดทั้งหมดด้วย JSON ดังนั้น คุณจึงสามารถแยกวิเคราะห์เพย์โหลดโดยใช้วิธีการหรือแพ็คเกจการแยกวิเคราะห์ JSON ทั่วไปได้

การตรวจสอบความถูกต้องของเพย์โหลด

เราลงนามเพย์โหลด "การแจ้งเตือนเหตุการณ์" ทั้งหมดด้วยลายเซ็น SHA256 และรวมลายเซ็นไว้ในส่วนหัว "X-Hub-Signature-256" ของคำขอ ซึ่งนำหน้าด้วย "sha256=" ทั้งนี้แม้คุณจะไม่ต้องตรวจสอบความถูกต้องของเพย์โหลด แต่ก็เป็นสิ่งที่คุณควรทำและเราขอแนะนำให้ทำเช่นกัน

วิธีตรวจสอบความถูกต้องของเพย์โหลดมีดังนี้

1. สร้างลายเซ็น SHA256 โดยใช้เพย์โหลดและข้อมูลลับของแอพในแอพของคุณ
2. เปรียบเทียบลายเซ็นของคุณกับลายเซ็นในส่วนหัว X-Hub-Signature-256 (ทุกอย่างที่อยู่หลัง sha256=) หากลายเซ็นตรงกัน แสดงว่าเพย์โหลดเป็นของแท้

ไฟล์ app.js อาจมีลักษณะดังนี้

// 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.");
    }
  }
}

การลองส่ง Webhooks อีกครั้ง

หากการแจ้งเตือนที่ส่งมายังเซิร์ฟเวอร์ของคุณไม่สำเร็จ เราจะลองอีก 2-3 ครั้งในทันที เซิร์ฟเวอร์ของคุณควรจัดการเรื่องการลบข้อมูลซ้ำซ้อนในกรณีเหล่านี้ หากเรายังคงไม่สามารถส่งการแจ้งเตือนได้หลังผ่านไปแล้ว 15 นาที จะมีการส่งการแจ้งเตือนไปยังบัญชีผู้พัฒนาของคุณ

หากส่งการแจ้งเตือนไม่สำเร็จต่อเนื่องถึง 1 ชั่วโมง คุณจะได้รับการแจ้งเตือน "ปิดใช้งาน Webhooks แล้ว" และแอพของคุณจะยกเลิกการสมัครรับข้อมูล Webhooks สำหรับเพจหรือบัญชีมืออาชีพบน Instagram เมื่อคุณแก้ไขปัญหาดังกล่าวแล้ว คุณจะต้องสมัครรับข้อมูล Webhooks อีกครั้ง

ทดสอบ Webhooks ของคุณ

หากต้องการทดสอบการตรวจสอบยืนยัน Webhook ให้เรียกใช้คำขอ cURL ต่อไปนี้ด้วยโทเค็นการตรวจสอบยืนยันของคุณ

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

หากการตรวจสอบยืนยัน Webhook ของคุณทำงานได้อย่างที่ควรจะเป็น คุณควรเห็นดังต่อไปนี้

• WEBHOOK_VERIFIED ลงบันทึกในบรรทัดคำสั่งที่การประมวลผลโหนดของคุณกำลังดำเนินอยู่
• CHALLENGE_ACCEPTED ลงบันทึกในบรรทัดคำสั่งที่คุณส่งคำขอ cURL

หากต้องการทดสอบ Webhook ของคุณ ให้ส่งคำขอ cURL ดังต่อไปนี้

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

หาก Webhook ของคุณทำงานได้อย่างที่ควรจะเป็น คุณควรเห็นดังต่อไปนี้

• TEST_MESSAGE ที่ลงบันทึกในบรรทัดคำสั่งที่การประมวลผลโหนดของคุณกำลังดำเนินอยู่
• EVENT RECEIVED ที่ลงบันทึกในบรรทัดคำสั่งที่คุณส่งคำขอ cURL

สมัครรับข้อมูล Webhooks ของ Meta

เมื่อตำแหน่งข้อมูลเซิร์ฟเวอร์ Webhooks หรือแอพตัวอย่างของคุณพร้อมแล้ว ให้ไปที่แดชบอร์ดของแอพ ของแอพคุณเพื่อสมัครรับข้อมูล Webhooks ของ Meta

ในตัวอย่างนี้ เราจะใช้แดชบอร์ดเพื่อกำหนดค่า Webhook และสมัครรับข้อมูลจากช่อง messages ซึ่งทุกครั้งที่ลูกค้าส่งข้อความมาที่แอพของคุณ ระบบจะส่งการแจ้งเตือนไปยังตำแหน่งข้อมูล Webhooks ของคุณ

1. ในแดชบอร์ดของแอพ ให้ไปที่ผลิตภัณฑ์ > Messenger > การตั้งค่า
   • Webhooks ของแพลตฟอร์ม Messenger บางรายการไม่พร้อมใช้งานสำหรับการส่งข้อความบน Instagram หากคุณกำลังใช้เพียง Webhooks สำหรับ Instagram และทราบว่า Webhooks ดังกล่าวพร้อมใช้งานสำหรับการส่งข้อความบน Instagram คุณสามารถสมัครรับข้อมูล Webhooks ได้ที่นี่ หากต้องการดูและสมัครรับข้อมูล Webhooks สำหรับการส่งข้อความบน Instagram เท่านั้น คุณสามารถไปที่การตั้งค่า Instagram ได้

2. ป้อน URL ของตำแหน่งข้อมูลของคุณลงในช่อง URL การเรียกกลับ และเพิ่มโทเค็นการตรวจสอบยืนยันของคุณลงในช่องโทเค็นการตรวจสอบยืนยัน เราจะรวมสตริงนี้ไว้ในคำขอให้ตรวจสอบยืนยันทั้งหมด หากคุณกำลังใช้หนึ่งในแอพตัวอย่างของเรา สตริงนี้ควรเป็นสตริงเดียวกับที่คุณใช้สำหรับตัวแปรการกำหนดค่า TOKEN ของแอพคุณ

3. สมัครรับข้อมูลช่องต่างๆ ที่คุณต้องการให้ระบบส่งการแจ้งเตือน แล้วคลิกบันทึก

4. ขั้นตอนสุดท้ายคือการสมัครรับข้อมูลแต่ละช่อง สมัครรับข้อมูลจากช่อง messages และส่ง "การแจ้งเตือนเหตุการณ์" ขั้นทดสอบ

   หากตำแหน่งข้อมูลของคุณได้รับการตั้งค่าอย่างถูกต้อง ตำแหน่งข้อมูลของคุณควรตรวจสอบความถูกต้องของเพย์โหลดและดำเนินการตามโค้ดใดก็ตามที่คุณตั้งไว้เมื่อตรวจสอบเสร็จเรียบร้อย หากคุณกำลังใช้แอพตัวอย่างของเรา ให้โหลด URL ของแอพในเว็บเบราว์เซอร์ของคุณ โดยระบบควรแสดงเนื้อหาของเพย์โหลด

คุณสามารถเปลี่ยนการสมัครรับข้อมูล Webhooks, โทเค็นการตรวจสอบยืนยัน หรือเวอร์ชั่นของ API ได้ตลอดเวลาโดยใช้แดชบอร์ดของแอพ

หมายเหตุ: เราขอแนะนำให้คุณใช้ API เวอร์ชั่นล่าสุดเพื่อรับข้อมูลทั้งหมดที่มีสำหรับ Webhook แต่ละรายการ

นอกจากนี้ คุณยังสามารถดำเนินการดังกล่าวได้โดยใช้โปรแกรมโดยใช้ตำแหน่งข้อมูล /app/subscriptions

ช่องของแพลตฟอร์ม Messenger ที่ใช้งานได้

เชื่อมต่อแอพของคุณ

คุณจะต้องเชื่อมต่อแอพ Webhooks กับเพจของคุณ และให้เพจของคุณสมัครรับข้อมูลเพื่อรับการแจ้งเตือน Webhooks ที่คุณต้องการรับ

เพิ่มแอพ

คุณสามารถเชื่อมต่อแอพกับเพจได้ใน Meta Business Suite > เครื่องมือทั้งหมด > แอพทางธุรกิจ

หมายเหตุ: คุณจะต้องให้แอพส่งข้อความทั้งหมดสำหรับธุรกิจของคุณสมัครรับข้อมูล Webhooks การส่งข้อความ

สมัครรับข้อมูลเพจของคุณ

คุณจะต้องให้เพจของคุณสมัครรับข้อมูลเพื่อรับการแจ้งเตือน Webhooks ที่คุณต้องการรับ

ข้อกำหนด

• โทเค็นการเข้าถึงเพจที่ขอจากบุคคลที่สามารถดำเนินงาน MODERATE บนเพจที่มีการสืบค้นได้
• pages_messaging และสิทธิ์การอนุญาต pages_manage_metadata

หากต้องการสมัครรับข้อมูลช่อง Webhooks ให้ส่งคำขอ POST ไปที่จุดเชื่อมโยง subscribed_apps ของเพจโดยใช้โทเค็นการเข้าถึงของเพจ

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

ตัวอย่างการตอบกลับ

{
  "success": "true"
}

หากต้องการดูว่าเพจของคุณติดตั้งแอพใดแล้วบ้าง ให้ส่งคำขอ 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"
      ]
    }
  ]
}

API จะส่งคืนชุดข้อมูลที่ว่างเปล่า หากเพจของคุณไม่ได้ติดตั้งแอพใดๆ

Graph API Explorer

คุณยังสามารถใช้ Graph API Explorer เพื่อส่งคำขอในการให้เพจของคุณสมัครรับข้อมูลช่อง Webhooks ได้อีกด้วย

1. เลือกแอพของคุณในเมนูดร็อปดาวน์ "แอพพลิเคชั่น"
2. คลิกที่ดร็อปดาวน์ "รับโทเค็น" แล้วเลือก "รับโทเค็นการเข้าถึงผู้ใช้" จากนั้นเลือกสิทธิ์การอนุญาต pages_manage_metadata การดำเนินการนี้จะแลกเปลี่ยนโทเค็นแอพของคุณเป็นโทเค็นการเข้าถึงผู้ใช้โดยได้รับสิทธิ์การอนุญาต pages_manage_metadata
3. คลิกรับโทเค็นอีกครั้ง แล้วเลือกเพจของคุณ การดำเนินการนี้จะแลกเปลี่ยนโทเค็นการเข้าถึงของผู้ใช้ของคุณเป็นโทเค็นการเข้าถึงเพจ
4. เปลี่ยนวิธีการดำเนินงานโดยคลิกเมนูดร็อปดาวน์ GET และเลือก POST
5. แทนที่การสืบค้น me?fields=id,name เริ่มต้นด้วย ID ของเพจ ตามด้วย /subscribed_apps จากนั้นส่งการสืบค้น

ข้อกำหนดสำหรับการเข้าถึง

แอพของคุณสามารถรับการแจ้งเตือนจากผู้ที่มีบทบาทในแอพ เช่น ผู้ดูแล ผู้พัฒนา หรือผู้ทดสอบของแอพได้โดยใช้เพียงสิทธิ์การเข้าถึงแบบมาตรฐาน ทั้งนี้ แอพจะต้องใช้สิทธิ์การเข้าถึงระดับสูง หากต้องการรับการแจ้งเตือนจากลูกค้าหรือผู้คนที่ไม่มีบทบาทในแอพของคุณ

โปรดเรียนรู้เพิ่มเติมเกี่ยวกับสิทธิ์การเข้าถึงแบบมาตรฐานและสิทธิ์การเข้าถึงระดับสูง รวมถึงข้อมูลที่เข้าถึงได้จากสิทธิ์การเข้าถึงแต่ละรูปแบบและข้อกำหนดสำหรับการนำไปใช้

ขั้นตอนถัดไป

เยี่ยมชมแอพตัวอย่างของเรา – ดาวน์โหลดโค้ดสำหรับแอพตัวอย่างของเราเพื่อเรียนรู้เพิ่มเติมเกี่ยวกับฟีเจอร์ต่างๆ ที่แพลตฟอร์ม Messenger มีให้ใช้งาน

ดูเพิ่มเติม

• เรียนรู้วิธีรับการแจ้งเตือนเมื่อมีการส่งต่อการสนทนาจากแอพหนึ่งไปยังอีกแอพหนึ่งโดยใช้โปรโตคอลการส่งมอบของ Messenger
• เรียนรู้เพิ่มเติมเกี่ยวกับ Webhooks ของ Meta สำหรับ API กราฟ