Webhooks của Meta cho Nền tảng Messenger

Với Webhooks của Meta, bạn có thể nhận được thông báo HTTP theo thời gian thực về những thay đổi đối với các đối tượng cụ thể trong đồ thị mạng xã hội của Meta. Ví dụ: chúng tôi có thể gửi thông báo cho bạn khi một người gửi tin nhắn đến Trang Facebook hoặc Tài khoản công việc trên Instagram mà bạn sở hữu. Với thông báo webhooks, bạn có thể theo dõi tin nhắn đến và cập nhật về trạng thái tin nhắn. Với thông báo webhooks, bạn cũng có thể tránh trường hợp đạt đến giới hạn tốc độ (sẽ xảy ra nếu bạn đã truy vấn điểm cuối Nền tảng Messenger để theo dõi các thay đổi này).

Để triển khai thành công Webhooks cho cuộc trò chuyện trên Messenger hoặc Instagram, bạn sẽ cần:

1. Tạo một điểm cuối trên máy chủ của bạn để nhận và xử lý thông báo Webhooks - các đối tượng JSON
2. Đặt cấu hình sản phẩm Webhooks của Meta trong Bảng điều khiển ứng dụng của bạn
3. Đăng ký nhận thông báo Webhooks của Meta mà bạn muốn
4. Cài đặt ứng dụng nhắn tin trên Trang Facebook được liên kết với doanh nghiệp hoặc Tài khoản công việc của bạn trên Instagram

Trước khi bạn bắt đầu

Trước khi bạn bắt đầu, chúng tôi giả định rằng bạn:

• Đã đọc và triển khai các thành phần cần thiết để phát triển với Meta trong phần Tổng quan về Nền tảng Messenger

Đặt cấu hình máy chủ Node.js

Máy chủ của bạn phải có khả năng xử lý 2 loại yêu cầu HTTPS: Yêu cầu xác minh và Thông báo sự kiện. Vì cả hai yêu cầu này đều sử dụng HTTPS nên máy chủ của bạn phải đặt cấu hình và cài đặt chính xác một chứng chỉ TLS hoặc SSL hợp lệ. Chứng chỉ tự ký không được hỗ trợ.

Các phần bên dưới sẽ giải thích nội dung trong mỗi loại yêu cầu và cách phản hồi nội dung đó.

Các mã mẫu hiển thị ở đây được lấy từ ứng dụng mẫu của chúng tôi trên GitHub . Hãy truy cập GitHub để xem ví dụ đầy đủ và biết thêm thông tin về cách thiết lập máy chủ webhooks.

Tạo điểm cuối

Khi tạo điểm cuối để nhận thông báo webhooks từ Nền tảng Messenger, file app.js sẽ có dạng như sau:

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

Mã này sẽ tạo ra một điểm cuối /webhook để chấp nhận các yêu cầu POST. Hãy kiểm tra để đảm bảo yêu cầu đó là thông báo webhook.

Trả về phản hồi 200 OK

Điểm cuối này phải trả về phản hồi 200 OK để cho Nền tảng Messenger biết rằng hệ thống đã nhận được sự kiện nên không cần phải gửi lại. Thông thường, bạn sẽ không gửi phản hồi này cho đến khi xử lý xong thông báo.

Phản hồi thông báo sự kiện

Điểm cuối cần phản hồi tất cả các thông báo:

• bằng phản hồi 200 OK HTTPS
• trong vòng 5 giây trở xuống

Mã dưới đây sẽ nằm trong app.post thuộc file app.js của bạn và sẽ có dạng như sau:

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

Yêu cầu xác minh

Mỗi khi bạn đặt cấu hình sản phẩm Webhooks trong Bảng điều khiển ứng dụng, chúng tôi sẽ gửi yêu cầu GET đến URL điểm cuối của bạn. Yêu cầu xác minh sẽ bao gồm các thông số chuỗi truy vấn sau đây, được thêm vào cuối URL điểm cuối của bạn. Các yêu cầu này sẽ có dạng như sau:

Yêu cầu xác minh mẫu

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

Xác thực yêu cầu xác minh

Mỗi khi nhận được yêu cầu xác minh, điểm cuối của bạn phải:

• Xác minh rằng giá trị hub.verify_token khớp với chuỗi mà bạn đặt trong trường Mã xác minh khi đặt cấu hình sản phẩm Webhooks trong Bảng điều khiển ứng dụng (bạn chưa thiết lập chuỗi mã này).
• Trả về giá trị hub.challenge.

File app.js của bạn sẽ có dạng như sau:

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

Lưu ý: PHP sẽ chuyển đổi dấu chấm (.) thành dấu gạch dưới (_) trong tên thông số .

Nếu bạn đang ở Bảng điều khiển ứng dụng và đặt cấu hình sản phẩm Webhooks (do đó, kích hoạt Yêu cầu xác minh), bảng điều khiển sẽ cho biết điểm cuối của bạn đã xác thực yêu cầu chính xác hay chưa. Nếu bạn đang sử dụng điểm cuối /app/subscriptions của API Đồ thị để đặt cấu hình sản phẩm Webhooks, API này sẽ phản hồi để cho biết có thành công hay không.

Thông báo sự kiện

Khi đặt cấu hình sản phẩm Webhooks, bạn sẽ đăng ký nhận các fields cụ thể trên loại object (ví dụ: trường messages trên đối tượng page). Mỗi khi có thay đổi đối với một trong các trường này, chúng tôi sẽ gửi yêu cầu POST đến điểm cuối của bạn kèm theo phần tải dữ liệu JSON mô tả sự thay đổi đó.

Ví dụ: nếu bạn đã đăng ký nhận trường message_reactions của đối tượng page và một khách hàng bày tỏ cảm xúc về tin nhắn mà ứng dụng của bạn gửi, chúng tôi sẽ gửi cho bạn một yêu cầu POST có dạng như sau:

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

          ...
        }
      ]
    }
  ]
}

Nội dung phần tải dữ liệu

Phần tải dữ liệu sẽ chứa một đối tượng mô tả sự thay đổi. Khi đặt cấu hình sản phẩm webhooks, bạn có thể cho biết liệu phần tải dữ liệu sẽ chỉ chứa tên của trường thông tin đã thay đổi hay sẽ bao gồm cả giá trị mới.

Chúng tôi định dạng tất cả các phần tải dữ liệu theo định dạng JSON. Vì vậy, bạn có thể phân tích cú pháp phần tải dữ liệu bằng các phương thức hoặc gói phân tích cú pháp JSON phổ biến.

Xác thực phần tải dữ liệu

Chúng tôi ký mọi phần tải dữ liệu của Thông báo sự kiện bằng chữ ký SHA256 và thêm chữ ký này vào tiêu đề "X-Hub-Signature-256" của yêu cầu, đứng trước là "sha256=". Bạn không phải xác thực phần tải dữ liệu. Tuy nhiên, chúng tôi khuyên bạn nên thực hiện việc này.

Cách xác thực phần tải dữ liệu:

1. Tạo chữ ký SHA256 bằng phần tải dữ liệu và Khóa bí mật của ứng dụng trong ứng dụng của bạn.
2. So sánh chữ ký của bạn với chữ ký trong tiêu đề X-Hub-Signature-256 (mọi nội dung sau sha256=). Nếu chữ ký khớp thì phần tải dữ liệu là thật.

File app.js sẽ có dạng như sau:

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

Thử phân phối lại Webhooks

Nếu không thể gửi thông báo đến máy chủ của bạn, chúng tôi sẽ lập tức thử gửi thêm vài lần nữa. Máy chủ của bạn sẽ xử lý việc bỏ trùng lặp trong những trường hợp này. Nếu chúng tôi vẫn không thể phân phối thông báo sau 15 phút, tài khoản nhà phát triển của bạn sẽ nhận được cảnh báo.

Nếu vẫn không thể phân phối thông báo trong vòng 1 giờ, bạn sẽ nhận được cảnh báo Webhooks đã bị vô hiệu hóa và ứng dụng của bạn sẽ bị hủy đăng ký nhận webhooks dành cho Trang hoặc Tài khoản công việc trên Instagram. Sau khi khắc phục vấn đề, bạn sẽ cần đăng ký lại Webhooks.

Thử nghiệm webhooks

Để thử nghiệm quy trình xác minh webhook, bạn cần chạy yêu cầu cURL sau đây cùng với mã xác minh của mình:

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

Nếu quy trình xác minh webhook hoạt động như dự kiến, bạn sẽ thấy thông báo sau:

• WEBHOOK_VERIFIED được ghi vào dòng lệnh đang chạy quy trình nút.
• CHALLENGE_ACCEPTED được ghi vào dòng lệnh mà bạn đã gửi yêu cầu cURL.

Để thử nghiệm webhook, bạn cần gửi yêu cầu cURL sau đây:

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

Nếu webhook hoạt động như dự kiến, bạn sẽ thấy thông báo sau:

• TEST_MESSAGE được ghi vào dòng lệnh đang chạy quy trình nút.
• EVENT RECEIVED được ghi vào dòng lệnh mà bạn đã gửi yêu cầu cURL.

Đăng ký Webhooks của Meta

Khi điểm cuối máy chủ webhooks hoặc ứng dụng mẫu của bạn đã sẵn sàng, hãy chuyển đến Bảng điều khiển ứng dụng của ứng dụng đó để đăng ký Webhooks của Meta.

Trong ví dụ này, chúng tôi sẽ sử dụng bảng điều khiển để đặt cấu hình Webhook và đăng ký trường messages. Bất cứ lúc nào khách hàng gửi tin nhắn đến ứng dụng, điểm cuối webhooks của bạn sẽ nhận được thông báo.

1. Trong Bảng điều khiển ứng dụng, hãy chuyển đến Sản phẩm > Messenger > Cài đặt.
   • Một số webhooks của Nền tảng Messenger không dùng được cho tính năng Nhắn tin trên Instagram. Nếu bạn chỉ triển khai webhooks cho Instagram và biết những webhooks dùng được cho tính năng nhắn tin trên Instagram, bạn có thể đăng ký webhooks ở đây. Nếu chỉ xem và đăng ký webhooks cho tính năng nhắn tin trên Instagram, bạn có thể chuyển đến phần Cài đặt Instagram.

2. Nhập URL của điểm cuối vào trường URL gọi lại rồi thêm mã xác minh vào trường Mã xác minh. Chúng tôi sẽ thêm chuỗi này vào tất cả Yêu cầu xác minh. Nếu bạn đang sử dụng một trong các ứng dụng mẫu của chúng tôi, đây phải là chuỗi mà bạn đã dùng cho biến cấu hình TOKEN của ứng dụng.

3. Đăng ký các trường bạn muốn nhận được thông báo rồi nhấp vào Lưu.

4. Bước cuối cùng là đăng ký từng trường. Hãy đăng ký nhận trường messages rồi gửi Thông báo sự kiện thử nghiệm.

   Nếu được thiết lập chính xác, điểm cuối của bạn phải xác thực phần tải dữ liệu và thực thi bất kỳ mã nào mà bạn đã thiết lập khi xác thực thành công. Nếu đang sử dụng ứng dụng mẫu của chúng tôi, hãy tải URL của ứng dụng vào trình duyệt web của bạn. Ứng dụng này sẽ hiển thị các nội dung của phần tải dữ liệu.

Bạn có thể thay đổi gói đăng ký Webhooks, mã xác minh hoặc phiên bản API bất cứ lúc nào qua Bảng điều khiển ứng dụng.

Lưu ý: Bạn nên sử dụng phiên bản API mới nhất để nhận được tất cả thông tin có sẵn cho mỗi webhook.

Bạn cũng có thể thực hiện việc này theo cách lập trình thông qua điểm cuối /app/subscriptions.

Các trường có sẵn trên Nền tảng Messenger

Kết nối ứng dụng

Bạn sẽ cần kết nối ứng dụng Webhooks với Trang của mình và đăng ký để Trang nhận các thông báo Webhooks mà bạn muốn.

Thêm ứng dụng

Bạn có thể kết nối ứng dụng với Trang trong Meta Business Suite > Tất cả công cụ > Ứng dụng dành cho doanh nghiệp

Lưu ý: Bạn sẽ cần đăng ký tất cả ứng dụng nhắn tin cho doanh nghiệp của mình với webhooks nhắn tin.

Đăng ký Trang

Bạn sẽ cần đăng ký để Trang nhận các thông báo Webhooks mà bạn muốn.

Yêu cầu

• Mã truy cập Trang do một người có thể thực hiện tác vụ MODERATE trên Trang đang được truy vấn yêu cầu
• Các quyền pages_messaging và pages_manage_metadata

Để đăng ký trường Webhooks, hãy gửi yêu cầu POST đến cạnh subscribed_apps của Trang bằng Mã truy cập Trang.

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

Phản hồi mẫu

{
  "success": "true"
}

Để xem Trang của bạn đã cài đặt ứng dụng nào, hãy gửi yêu cầu GET:

Yêu cầu mẫu

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

Phản hồi mẫu

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "APP-ID"
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

Nếu Trang của bạn chưa cài đặt ứng dụng nào, API sẽ trả về tập dữ liệu trống.

Trình khám phá API Đồ thị

Bạn cũng có thể dùng Trình khám phá API Đồ thị để gửi yêu cầu đăng ký nhận trường Webhooks cho Trang của mình.

1. Chọn ứng dụng của bạn trong menu thả xuống Ứng dụng.
2. Nhấp vào menu thả xuống Lấy mã và chọn Lấy mã truy cập người dùng, sau đó chọn quyền pages_manage_metadata. Khi đó, mã ứng dụng của bạn sẽ được đổi lấy mã truy cập dành cho Người dùng cùng với quyền pages_manage_metadata.
3. Nhấp lại vào Lấy mã rồi chọn Trang của bạn. Khi đó, mã truy cập dành cho Người dùng sẽ được đổi lấy mã truy cập Trang.
4. Nhấp vào menu thả xuống GET rồi chọn POST để thay đổi phương thức thao tác.
5. Thay thế truy vấn me?fields=id,name mặc định bằng ID của Trang rồi đến /subscribed_apps, sau đó gửi truy vấn.

Yêu cầu đối với quyền truy cập

Để nhận được thông báo từ những người có vai trò trên ứng dụng của bạn - chẳng hạn như quản trị viên ứng dụng, nhà phát triển hoặc người dùng thử, ứng dụng đó chỉ cần có Quyền truy cập tiêu chuẩn. Để nhận được thông báo từ khách hàng, những người không có vai trò trên ứng dụng của bạn, ứng dụng đó sẽ cần có Quyền truy cập nâng cao.

Tìm hiểu thêm về Quyền truy cập tiêu chuẩn và Quyền truy cập nâng cao , dữ liệu có thể truy cập được bằng mỗi loại quyền này và các yêu cầu đối với quy trình triển khai.

Bước tiếp theo

Tham khảo ứng dụng mẫu của chúng tôi - Tải xuống mã cho ứng dụng mẫu của chúng tôi để tìm hiểu thêm về các tính năng mà Nền tảng Messenger cung cấp.

Xem thêm

• Tìm hiểu cách nhận thông báo khi một cuộc trò chuyện được chuyển từ ứng dụng này sang ứng dụng khác thông qua Giao thức chuyển giao trên Messenger
• Tìm hiểu thêm về Webhooks cho API Đồ thị của Meta