Hướng dẫn bắt đầu nhanh

Nếu bạn chưa thiết lập, hãy làm theo hướng dẫn thiết lập ứng dụng của chúng tôi để thiết lập ứng dụng trên Facebook của bạn cho mục đích sử dụng với Nền tảng Messenger.

Mọi yêu cầu đến API Nền tảng Messenger đều được xác thực bằng cách thêm mã truy cập ở cấp độ trang vào thông số access_token của chuỗi truy vấn.

Nếu bạn chưa thêm khi thiết lập ứng dụng trên Facebook, hãy tạo mã truy cập trang theo cách sau:

Bạn nên giữ bảo mật các thông tin nhạy cảm như mã truy cập trang bằng cách không mã hóa cứng thông tin đó vào webhook của mình.

Để thực hiện điều này, hãy thêm thông tin sau vào các biến môi trường của bạn, trong đó <PAGE_ACCESS_TOKEN> là mã truy cập bạn vừa tạo và <VERIFY_TOKEN> là một chuỗi ngẫu nhiên bạn đặt để xác minh webhook của mình:

PAGE_ACCESS_TOKEN="

Bây giờ, tất cả những gì bạn phải làm là thêm mã truy cập trang và mã xác minh vào đầu file app.js để sử dụng các mã đó trong logic webhook của mình:

const PAGE_ACCESS_TOKEN = process.env.PAGE_ACCESS_TOKEN;
const VERIFY_TOKEN = process.env.VERIFY_TOKEN;

Để bắt đầu, chúng tôi sẽ tắt 3 hàm xử lý các loại sự kiện webhook đến mà chúng tôi muốn hỗ trợ, cũng như phản hồi qua API gửi. Để thực hiện điều này, hãy thêm các hàm sau vào file app.js của bạn:

// Handles messages events
function handleMessage(sender_psid, received_message) {

}

// Handles messaging_postbacks events
function handlePostback(sender_psid, received_postback) {

}

// Sends response messages via the Send API
function callSendAPI(sender_psid, response) {
  
}

Để trả lời mọi người trên Messenger, trước hết, chúng tôi cần biết họ là ai. Trong Messenger, chúng tôi thực hiện điều này bằng cách lấy ID trong trang (PSID) của người gửi tin nhắn từ sự kiện webhook đến.

PSID là gì?

Mỗi người sẽ được chỉ định một ID trong trang (PSID) duy nhất cho mỗi Trang Facebook mà họ bắt đầu cuộc trò chuyện. PSID được dùng để nhận dạng một người khi họ gửi tin nhắn.

Nếu đã hoàn tất một trong các tùy chọn ở phần Dự án dành cho người mới bắt đầu nêu trên, bạn sẽ có điểm cuối /webhook cơ bản để chấp nhận các yêu cầu POST và ghi lại phần nội dung của sự kiện webhook nhận được có dạng như sau:

app.post('/webhook', (req, res) => {  

  // Parse the request body from the POST
  let body = req.body;

  // Check the webhook event is from a Page subscription
  if (body.object === 'page') {

    // Iterate over each entry - there may be multiple if batched
    body.entry.forEach(function(entry) {

      // Get the webhook event. entry.messaging is an array, but 
      // will only ever contain one event, so we get index 0
      let webhook_event = entry.messaging[0];
      console.log(webhook_event);
      
    });

    // Return a '200 OK' response to all events
    res.status(200).send('EVENT_RECEIVED');

  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }

});

Để lấy PSID của người gửi, hãy cập nhật mã sau cho khối body.entry.forEach để trích xuất PSID từ thuộc tính sender.id của sự kiện:

Chúng tôi muốn trải nghiệm của mình có khả năng xử lý 2 loại sự kiện webhook: messages và messaging_postback. Tên của loại sự kiện không có trong phần nội dung sự kiện. Tuy nhiên, chúng tôi có thể xác định sự kiện đó bằng cách kiểm tra một số thuộc tính đối tượng.

Sự kiện webhook là gì?

Nền tảng Messenger gửi sự kiện webhook để thông báo cho bạn về các hành động diễn ra trong Messenger. Sự kiện sẽ được gửi ở định dạng JSON dưới dạng yêu cầu POST đến webhook của bạn. Để biết thêm thông tin, hãy xem phần Sự kiện webhook.

Để thực hiện điều này, hãy cập nhật một điều kiện cho khối body.entry.forEach trong webhook của bạn để kiểm tra xem sự kiện nhận được chứa thuộc tính message hay postback. Chúng tôi cũng sẽ thêm lệnh gọi đến các hàm handleMessage() và handlePostback() mà chúng tôi đã tắt trước đó:

body.entry.forEach(function(entry) {

  // Gets the body of the webhook event
  let webhook_event = entry.messaging[0];
  console.log(webhook_event);


  // Get the sender PSID
  let sender_psid = webhook_event.sender.id;
  console.log('Sender PSID: ' + sender_psid);

  // Check if the event is a message or postback and
  // pass the event to the appropriate handler function
  if (webhook_event.message) {
    handleMessage(sender_psid, webhook_event.message);        
  } else if (webhook_event.postback) {
    handlePostback(sender_psid, webhook_event.postback);
  }
  
});

Bây giờ, tin nhắn đến của chúng tôi đang được chuyển đến các hàm xử lý thích hợp. Chúng tôi sẽ cập nhật hàm handleMessage() để xử lý và trả lời các tin nhắn văn bản cơ bản. Để thực hiện điều này, hãy cập nhật mã để xác định phần tải dữ liệu tin nhắn của phản hồi rồi chuyển phần tải dữ liệu đó vào callSendAPI(). Vì muốn trả lời bằng tin nhắn văn bản cơ bản nên chúng tôi xác định một đối tượng JSON có thuộc tính "text":

function handleMessage(sender_psid, received_message) {

  let response;

  // Check if the message contains text
  if (received_message.text) {    

    // Create the payload for a basic text message
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an image!`
    }
  }  
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Đã đến lúc gửi tin nhắn đầu tiên qua API Gửi của Nền tảng Messenger!

Trong hàm handleMessage(), chúng tôi đang gọi callSendAPI() nên bây giờ cần cập nhật lệnh gọi này để tạo phần nội dung yêu cầu đầy đủ rồi gửi yêu cầu đó đến Nền tảng Messenger. Yêu cầu đến API Gửi có 2 thuộc tính:

• recipient: Đặt người nhận dự kiến của tin nhắn. Trong trường hợp này, chúng tôi xác định người đó bằng PSID của họ.
• message: Đặt thông tin chi tiết về tin nhắn sẽ gửi. Ở đây, chúng tôi sẽ đặt thuộc tính này là đối tượng tin nhắn đã chuyển vào từ hàm handleMessage().

Để tạo phần nội dung yêu cầu, hãy cập nhật hàm chưa hoàn chỉnh của lệnh gọi callSendAPI() thành như sau:

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }
}

Bây giờ, tất cả những gì chúng tôi phải làm là gửi tin nhắn bằng cách gửi yêu cầu POST đến API Gửi tại địa chỉ https://graph.facebook.com/v2.6/me/messages.

Lưu ý rằng bạn phải thêm PAGE_ACCESS_TOKEN của mình vào thông số access_token của chuỗi truy vấn URL.

const request = require('request');

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }

  // Send the HTTP request to the Messenger Platform
  request({
    "uri": "https://graph.facebook.com/v2.6/me/messages",
    "qs": { "access_token": process.env.PAGE_ACCESS_TOKEN },
    "method": "POST",
    "json": request_body
  }, (err, res, body) => {
    if (!err) {
      console.log('message sent!')
    } else {
      console.error("Unable to send message:" + err);
    }
  }); 
}

Hãy thử nghiệm!

Trong Messenger, hãy gửi một tin nhắn văn bản khác đến Trang Facebook của bạn. Bạn sẽ nhận được phản hồi tự động từ trải nghiệm Messenger của mình. Phản hồi này sẽ trả lời tin nhắn của bạn và nhắc bạn gửi hình ảnh.

Vì phản hồi của chúng tôi nhắc người nhận tin nhắn gửi hình ảnh nên bước tiếp theo là cập nhật mã để xử lý file đính kèm. Nền tảng Messenger sẽ tự động lưu lại và cung cấp những file đính kèm đã gửi qua URL trong thuộc tính payload.url của từng chỉ mục trong mảng attachments. Vì vậy, chúng tôi cũng sẽ trích xuất thông tin này từ sự kiện.

Những loại file đính kèm nào được hỗ trợ?

Trải nghiệm Messenger của bạn có thể gửi và nhận hầu hết các loại tài sản, bao gồm cả hình ảnh, âm thanh, video và file. File phương tiện sẽ hiển thị và thậm chí có thể phát trong cuộc trò chuyện, giúp bạn tạo ra trải nghiệm đa phương tiện.

Để xác định xem tin nhắn có phải là file đính kèm hay không, hãy cập nhật điều kiện trong hàm handleMessage() của bạn để kiểm tra xem received_message có thuộc tính attachments hay không rồi trích xuất URL của file đính kèm đó. Trong bot thực tế, chúng tôi sẽ lặp lại mảng để kiểm tra nhiều file đính kèm. Tuy nhiên, với mục đích của hướng dẫn bắt đầu nhanh này, chúng tôi sẽ chỉ lấy file đính kèm đầu tiên.

function handleMessage(sender_psid, received_message) {

  let response;

  // Checks if the message contains text
  if (received_message.text) {
    
    // Creates the payload for a basic text message, which
    // will be added to the body of our request to the Send API
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an attachment!`
    }

  } else if (received_message.attachments) {
  
    // Gets the URL of the message attachment
    let attachment_url = received_message.attachments[0].payload.url;
  
  } 
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Tiếp theo, chúng tôi sẽ trả lời hình ảnh bằng tin nhắn theo mẫu chung. Mẫu chung là loại tin nhắn có cấu trúc thường dùng nhất và cho phép bạn gửi hình ảnh, văn bản cũng như các nút trong một tin nhắn.

Có các mẫu tin nhắn khác không?

Có! Nền tảng Messenger cung cấp một loạt mẫu tin nhắn hữu ích, mỗi mẫu được thiết kế nhằm hỗ trợ một cấu trúc tin nhắn phổ biến khác nhau, bao gồm cả danh sách, biên lai, nút và hơn thế nữa. Để biết toàn bộ thông tin, hãy xem phần Mẫu.

Mẫu tin nhắn được xác định trong thuộc tính attachment của tin nhắn, có chứa thuộc tính type và payload. Trong thuộc tính payload, chúng tôi sẽ đặt thông tin chi tiết về mẫu chung trong các thuộc tính sau:

• template_type: Đặt loại mẫu dùng cho tin nhắn. Chúng tôi đang sử dụng mẫu chung nên giá trị sẽ là "generic" (chung).
• elements: Đặt các thuộc tính tùy chỉnh của mẫu. Đối với mẫu chung, chúng tôi sẽ chỉ định tiêu đề, tiêu đề phụ, hình ảnh và 2 nút đăng lại.

Đối với tin nhắn có cấu trúc, chúng tôi sẽ sử dụng attachment_url đã nhận được dưới dạng image_url để hiển thị trong mẫu và thêm một số nút đăng lại để cho phép người nhận tin nhắn trả lời. Để tạo phần tải dữ liệu tin nhắn và gửi mẫu chung, hãy cập nhật hàm handleMessage() thành như sau:

Bước cuối cùng là xử lý sự kiện webhook messaging_postbacks sẽ được gửi đi khi người nhận tin nhắn nhấn vào một trong các nút đăng lại trong mẫu chung của chúng tôi.

Tôi có thể làm gì với yêu cầu đăng lại?

Nút đăng lại sẽ gửi sự kiện webhook messaging_postbacks đến webhook của bạn. Sự kiện này có chứa một chuỗi tùy chỉnh lên đến 1.000 ký tự trong thuộc tính payload. Nhờ đó, bạn có thể dễ dàng triển khai các phần tải dữ liệu yêu cầu đăng lại khác nhau để phân tích cú pháp và trả lời bằng những hành vi cụ thể.

Vì mẫu chung của chúng tôi cho phép người nhận tin nhắn chọn trong 2 nút đăng lại, nên chúng tôi sẽ trả lời dựa trên giá trị của thuộc tính payload trong sự kiện đăng lại. Để thực hiện điều này, hãy cập nhật hàm chưa hoàn chỉnh handlePostback() của bạn thành như sau: