Nhận và trả lời hoạt động tương tác của người dùng

Trang này mô tả cách ứng dụng Google Chat có thể nhận và phản hồi các lượt tương tác của người dùng, còn gọi là sự kiện tương tác của ứng dụng Google Chat.

Trang này mô tả cách thực hiện những việc sau:

• Định cấu hình ứng dụng Chat để nhận các sự kiện tương tác.
• Xử lý sự kiện tương tác trên cơ sở hạ tầng của bạn.
• Nếu thích hợp, hãy phản hồi các sự kiện tương tác.

Điều kiện tiên quyết

Ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat có tính tương tác, hãy hoàn thành một trong các hướng dẫn bắt đầu nhanh sau đây dựa trên cấu trúc ứng dụng mà bạn muốn sử dụng:

• Dịch vụ HTTP với Google Cloud Functions
• Google Apps Script
• Dialogflow CX của Google Cloud
• Google Cloud Pub/Sub

Các loại sự kiện tương tác

Sự kiện tương tác với ứng dụng Google Chat đại diện cho mọi hành động mà người dùng thực hiện để gọi hoặc tương tác với ứng dụng Chat, chẳng hạn như @thắc mắc về ứng dụng Chat hoặc thêm ứng dụng đó vào không gian.

Khi người dùng tương tác với một ứng dụng trong Chat, Google Chat sẽ gửi cho ứng dụng Chat một sự kiện tương tác, được biểu thị dưới dạng loại Event trong API Chat. Ứng dụng Chat có thể sử dụng sự kiện để xử lý hoạt động tương tác và phản hồi bằng tin nhắn (không bắt buộc).

Đối với mỗi loại tương tác của người dùng, Google Chat sẽ gửi một loại sự kiện tương tác khác nhau để giúp ứng dụng Chat xử lý từng loại sự kiện cho phù hợp. Loại sự kiện tương tác được biểu thị bằng đối tượng eventType.

Ví dụ: Google Chat sử dụng loại sự kiện ADDED_TO_SPACE cho mọi hoạt động tương tác mà người dùng thêm ứng dụng Chat vào một không gian để ứng dụng Chat có thể phản hồi ngay lập tức bằng tin nhắn chào mừng trong không gian.

Hình 1: Khi người dùng thêm một ứng dụng Chat vào không gian, ứng dụng Chat sẽ nhận được một sự kiện tương tác ADDED_TO_SPACE mà ứng dụng Chat xử lý để gửi lời chào trong không gian.

Bảng sau đây cho biết các hoạt động tương tác phổ biến của người dùng, loại sự kiện tương tác mà ứng dụng trong Chat nhận được và cách các ứng dụng trong Chat thường phản hồi:

Hoạt động tương tác của người dùng	eventType	Câu trả lời thông thường của một ứng dụng Chat
Người dùng gọi một ứng dụng Chat bằng cách @đề cập đến ứng dụng đó hoặc sử dụng lệnh dấu gạch chéo.	MESSAGE	Ứng dụng Chat trả lời dựa trên nội dung của tin nhắn. Ví dụ: ứng dụng Chat trả lời lệnh /about bằng một thông báo giải thích các tác vụ mà ứng dụng Chat có thể thực hiện.
Người dùng thêm ứng dụng Chat vào một không gian.	ADDED_TO_SPACE	Ứng dụng Chat gửi một thông báo làm quen với ứng dụng để giải thích chức năng của ứng dụng và cách người dùng trong không gian có thể tương tác với ứng dụng đó.
Một người dùng xoá ứng dụng trong Chat khỏi không gian.	REMOVED_FROM_SPACE	Ứng dụng Chat sẽ xoá mọi thông báo đến được định cấu hình cho không gian (chẳng hạn như xoá webhook) và giải phóng bộ nhớ trong.
Người dùng nhấp vào một nút trên thẻ trong tin nhắn, hộp thoại hoặc trang chủ của ứng dụng Chat.	CARD_CLICKED	Ứng dụng Chat sẽ xử lý và lưu trữ mọi dữ liệu mà người dùng đã gửi hoặc trả về một thẻ khác.
Người dùng mở trang chủ của ứng dụng Chat bằng cách nhấp vào thẻ Trang chủ trong tin nhắn 1:1.	APP_HOME	Ứng dụng Chat trả về một thẻ tĩnh hoặc thẻ tương tác từ trang chủ.
Người dùng gửi một biểu mẫu trên trang chủ của ứng dụng Chat.	SUBMIT_FORM	Ứng dụng Chat sẽ xử lý và lưu trữ mọi dữ liệu mà người dùng đã gửi hoặc trả về một thẻ khác.

Để xem tất cả sự kiện tương tác được hỗ trợ, hãy xem tài liệu tham khảo về EventType.

Sự kiện tương tác từ hộp thoại

Nếu ứng dụng Chat của bạn mở hộp thoại, thì sự kiện tương tác sẽ chứa thông tin bổ sung sau đây mà bạn có thể sử dụng để xử lý phản hồi:

• isDialogEvent được đặt thành true.
• DialogEventType làm rõ liệu hoạt động tương tác có kích hoạt một hộp thoại để mở, gửi thông tin từ một hộp thoại hay đóng một hộp thoại hay không.

Bảng sau đây trình bày các hoạt động tương tác phổ biến với hộp thoại, các loại sự kiện hộp thoại tương ứng và nội dung mô tả về cách các ứng dụng Chat thường phản hồi:

Người dùng tương tác với hộp thoại	Loại sự kiện hộp thoại	Phản hồi thông thường
Người dùng kích hoạt một yêu cầu hộp thoại. Ví dụ: người dùng sử dụng lệnh dấu gạch chéo hoặc nhấp vào một nút trong tin nhắn.	REQUEST_DIALOG	Ứng dụng Chat sẽ mở hộp thoại.
Người dùng gửi thông tin trong hộp thoại bằng cách nhấp vào một nút.	SUBMIT_DIALOG	Ứng dụng Chat sẽ chuyển đến một hộp thoại khác hoặc đóng hộp thoại để hoàn tất lượt tương tác.
Người dùng thoát hoặc đóng hộp thoại trước khi gửi thông tin.	CANCEL_DIALOG	Nếu muốn, ứng dụng Chat có thể trả lời bằng một tin nhắn mới hoặc cập nhật tin nhắn hay thẻ mà người dùng đã mở hộp thoại.

Để biết thêm thông tin, hãy xem phần Mở hộp thoại tương tác.

Nhận sự kiện tương tác trong ứng dụng trong Chat

Phần này mô tả cách nhận và xử lý các sự kiện tương tác cho ứng dụng Chat.

Định cấu hình ứng dụng Chat để nhận sự kiện tương tác

Không phải ứng dụng Chat nào cũng có tính tương tác. Ví dụ: webhook đến chỉ có thể gửi tin nhắn đi và không thể phản hồi người dùng. Nếu đang xây dựng một ứng dụng Chat tương tác, bạn phải chọn một điểm cuối cho phép ứng dụng Chat nhận, xử lý và phản hồi các sự kiện tương tác. Để tìm hiểu thêm về cách thiết kế ứng dụng Chat, hãy xem phần Cấu trúc triển khai ứng dụng Chat.

Đối với mỗi tính năng tương tác mà bạn muốn xây dựng, bạn phải cập nhật cấu hình trong Chat API để Google Chat có thể gửi các sự kiện tương tác có liên quan đến ứng dụng Chat:

1. Trong bảng điều khiển Google Cloud, hãy truy cập trang API Chat rồi nhấp vào trang Cấu hình:

   Chuyển đến trang Cấu hình API Chat

2. Trong phần Tính năng tương tác, hãy xem lại chế độ cài đặt và cập nhật dựa trên các tính năng mà bạn muốn tạo:

   Trường	Mô tả
   Chức năng	Bắt buộc. Một tập hợp các trường xác định cách ứng dụng Chat có thể tương tác với người dùng: Nhận tin nhắn 1:1: Người dùng có thể tìm và nhắn tin trực tiếp cho ứng dụng Chat trong Google Chat. Tham gia không gian và cuộc trò chuyện nhóm: Người dùng có thể thêm ứng dụng Chat vào không gian và cuộc trò chuyện nhóm.
   Chế độ cài đặt kết nối	Bắt buộc. Điểm cuối cho ứng dụng Chat, là một trong những điểm sau: URL điểm cuối HTTP: Một điểm cuối HTTPS lưu trữ hoạt động triển khai ứng dụng Chat. Apps Script: Mã triển khai cho một dự án Apps Script triển khai ứng dụng Chat. Tên chủ đề trên Cloud Pub/Sub: Chủ đề Pub/Sub mà ứng dụng Chat đăng ký dưới dạng một điểm cuối. Dialogflow: Đăng ký ứng dụng Chat bằng tính năng tích hợp Dialogflow. Để biết thêm thông tin, hãy xem bài viết Tạo một ứng dụng Google Chat bằng Dialogflow hiểu được ngôn ngữ tự nhiên.
   Lệnh dấu gạch chéo	Không bắt buộc. Các lệnh có thể hiển thị cho người dùng trong Google Chat. Cho phép người dùng xem các hành động cốt lõi của ứng dụng Chat trong Google Chat và chọn một hành động cụ thể mà họ muốn tương tác. Để biết thêm thông tin, hãy xem phần Phản hồi lệnh gạch chéo dưới dạng ứng dụng Chat.
   Bản xem trước đường liên kết	Không bắt buộc. Mẫu URL mà ứng dụng Chat nhận dạng và cung cấp nội dung bổ sung khi người dùng gửi đường liên kết. Để biết thêm thông tin, hãy xem bài viết Xem trước đường liên kết.
   Chế độ hiển thị	Không bắt buộc. Tối đa 5 cá nhân hoặc một hoặc nhiều Nhóm trên Google có thể xem và cài đặt ứng dụng Chat của bạn. Hãy sử dụng trường này để kiểm thử ứng dụng Chat hoặc chia sẻ ứng dụng Chat với nhóm của bạn. Để biết thêm thông tin, hãy xem bài viết Kiểm thử các tính năng tương tác.

3. Nhấp vào Lưu. Khi bạn lưu cấu hình ứng dụng Chat, ứng dụng Chat sẽ có sẵn cho những người dùng được chỉ định trong tổ chức Google Workspace của bạn.

Ứng dụng Chat hiện đã được định cấu hình để nhận các sự kiện tương tác từ Google Chat.

Xử lý các lần thử lại lệnh gọi HTTP đến dịch vụ của bạn

Nếu một yêu cầu HTTPS đến dịch vụ của bạn không thành công (chẳng hạn như hết thời gian chờ, lỗi mạng tạm thời hoặc mã trạng thái HTTPS không phải 2xx), thì Google Chat có thể thử phân phối lại một vài lần trong vòng vài phút (nhưng không đảm bảo điều này). Do đó, ứng dụng Chat có thể nhận được cùng một tin nhắn vài lần trong một số tình huống nhất định. Nếu yêu cầu hoàn tất thành công nhưng trả về một tải trọng tin nhắn không hợp lệ, thì Google Chat sẽ không thử lại yêu cầu.

Xử lý hoặc phản hồi sự kiện tương tác

Phần này giải thích cách các ứng dụng Google Chat có thể xử lý và phản hồi các sự kiện tương tác.

Sau khi nhận được một sự kiện tương tác từ Google Chat, ứng dụng Chat của bạn có thể phản hồi theo nhiều cách. Trong nhiều trường hợp, các ứng dụng tương tác trong Chat sẽ trả lời người dùng bằng tin nhắn. Ứng dụng Google Chat cũng có thể tra cứu một số thông tin từ một nguồn dữ liệu, ghi lại thông tin về sự kiện tương tác hoặc bất cứ điều gì khác. Hành vi xử lý này về cơ bản là yếu tố xác định ứng dụng Google Chat.

Để phản hồi đồng bộ, ứng dụng Chat phải phản hồi trong vòng 30 giây và phản hồi phải được đăng trong không gian diễn ra tương tác. Nếu không, ứng dụng Chat có thể phản hồi không đồng bộ.

Đối với mỗi sự kiện tương tác, các ứng dụng trong Chat sẽ nhận được một nội dung yêu cầu, là tải trọng JSON đại diện cho sự kiện đó. Bạn có thể sử dụng thông tin này để xử lý phản hồi. Để biết ví dụ về các gói dữ liệu sự kiện, hãy xem phần Các loại sự kiện tương tác với ứng dụng trong Chat.

Sơ đồ sau đây minh hoạ cách ứng dụng Google Chat thường xử lý hoặc phản hồi các loại sự kiện tương tác:

Trả lời theo thời gian thực

Sự kiện tương tác cho phép các ứng dụng trong Chat phản hồi theo thời gian thực hoặc đồng bộ. Phản hồi đồng bộ không yêu cầu xác thực.

Để phản hồi theo thời gian thực, ứng dụng Chat phải trả về một đối tượng Message. Để trả lời bằng tin nhắn trong không gian, đối tượng Message có thể chứa các đối tượng text, cardsV2 và accessoryWidgets. Để sử dụng với các loại phản hồi khác, hãy xem hướng dẫn sau:

• Mở hộp thoại tương tác
• Đường liên kết đến bản xem trước
• Xử lý thông tin do người dùng gửi

Lưu ý: Đối với các sự kiện tương tác REMOVED_FROM_SPACE, các ứng dụng trong Chat không thể phản hồi bằng đối tượng Message vì chúng không còn nằm trong không gian.

Trả lời bằng tin nhắn

Trong ví dụ này, ứng dụng Chat sẽ tạo và gửi tin nhắn văn bản bất cứ khi nào tin nhắn đó được thêm vào không gian. Để tìm hiểu các phương pháp hay nhất dành cho người dùng mới, hãy xem phần Giới thiệu người dùng làm quen với ứng dụng Chat.

Để gửi tin nhắn văn bản khi người dùng thêm ứng dụng Chat vào một không gian, ứng dụng Chat sẽ phản hồi một sự kiện tương tác ADDED_TO_SPACE. Để phản hồi sự kiện tương tác ADDED_TO_SPACE bằng tin nhắn văn bản, hãy dùng mã sau:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

Mã mẫu trả về thông báo văn bản sau:

Phản hồi không đồng bộ

Đôi khi, các ứng dụng trong Chat phải phản hồi một sự kiện tương tác sau 30 giây hoặc thực hiện các nhiệm vụ bên ngoài không gian nơi sự kiện tương tác được tạo ra. Ví dụ: Một ứng dụng Chat có thể cần phản hồi cho người dùng sau khi hoàn thành một tác vụ chạy trong thời gian dài. Trong trường hợp này, các ứng dụng Chat có thể phản hồi không đồng bộ bằng cách gọi API Google Chat.

Để tạo tin nhắn bằng API Chat, hãy xem phần Tạo tin nhắn. Để biết hướng dẫn về cách sử dụng các phương thức API Chat khác, hãy xem bài viết Tổng quan về Chat API.

Chủ đề có liên quan

• Gửi tin nhắn
• Mở hộp thoại tương tác
• Đường liên kết đến bản xem trước
• Đọc dữ liệu biểu mẫu do người dùng nhập trên thẻ
• Phản hồi lệnh dấu gạch chéo
• Tạo trang chủ cho ứng dụng Chat
• Xác minh yêu cầu của Chat
• Kiểm thử các tính năng có tính tương tác cho các ứng dụng của Google Chat