Nhận và phản hồi các sự kiện tương tác

Trang này mô tả cách ứng dụng Google Chat của bạn có thể nhận và phản hồi các hoạt động tương tác của người dùng, còn được 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

• Tài khoản Google Workspace dành cho doanh nghiệp có quyền truy cập vào Google Chat.
• Tạo một dự án trên Google Cloud.
• Định cấu hình màn hình xin phép bằng OAuth.
• Bật Google Chat API.

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

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

Khi người dùng tương tác với một ứng dụng 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 Chat API. Ứng dụng Chat có thể sử dụng sự kiện này để xử lý hoạt động tương tác và tuỳ ý phản hồi bằng một tin nhắn.

Đối với mỗi loại lượt 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 của bạn 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 khi người dùng thêm ứng dụng Chat vào một không gian, để ứng dụng Chat có thể ngay lập tức phản hồi bằng một thông báo chào mừng 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 Chat nhận được và cách ứng dụng Chat thường phản hồi:

Để xem tất cả cá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ể 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 hộp thoại mở, gửi thông tin từ hộp thoại hay đóng hộp thoại.

Bảng sau đây cho thấ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:

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

Nhận sự kiện tương tác trong ứng dụng 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 của bạn.

Đị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 tạo một ứng dụng Chat có tính tương tác, bạn phải chọn một điểm cuối cho phép ứng dụng Chat của bạn 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 tạo, 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 của bạn:

1. Trong Cloud Console của Google, hãy chuyển đến trang Chat API rồi nhấp vào trang Configuration (Cấu hình):

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

2. Trong phần Tính năng tương tác, hãy xem xét các chế độ cài đặt và cập nhật dựa trên những 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. Theo mặc định, người dùng có thể tìm thấy 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 cuối sau: URL điểm cuối HTTP: Một điểm cuối HTTPS lưu trữ việc triển khai ứng dụng Chat. Apps Script: Mã nhận dạng triển khai cho một dự án Apps Script triển khai một ứng dụng Chat. Tên chủ đề trên Cloud Pub/Sub: Một chủ đề Pub/Sub mà ứng dụng Chat đăng ký làm điểm cuối. Dialogflow: Đăng ký ứng dụng Chat bằng một chế độ 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 Dialogflow trên Google Chat có thể hiểu ngôn ngữ tự nhiên.
   Lệnh	Không bắt buộc. Lệnh dấu gạch chéo và lệnh nhanh cho ứng dụng Chat. Lệnh cho phép người dùng yêu cầu một hành động hoặc sử dụng một tính năng cụ thể của ứng dụng Chat. Để biết thêm thông tin, hãy xem phần Phản hồi lệnh của ứng dụng Google Chat.
   Câu lệnh mở đầu	Không bắt buộc. (science Bản dùng trước cho nhà phát triển) Tối đa 3 câu lệnh mặc định ban đầu xuất hiện khi người dùng mở một tin nhắn trực tiếp 1:1 trống bằng ứng dụng Chat. Câu lệnh có thể điền sẵn văn bản vào vùng soạn thảo (có hỗ trợ bản địa hoá đa ngôn ngữ) hoặc kích hoạt trực tiếp một lệnh gạch chéo/lệnh nhanh. Để biết thêm thông tin, hãy xem phần Định cấu hình câu lệnh bắt đầu.
   Bản xem trước đường liên kết	Không bắt buộc. Cá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 phần 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 Groups 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 của bạn 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 của bạn hiện đã được định cấu hình để nhận các sự kiện tương tác từ Google Chat.

Thiết lập câu lệnh mở đầu

Câu lệnh bắt đầu giúp người dùng khám phá chức năng của ứng dụng Chat khi họ mở một tin nhắn trực tiếp 1:1 trống với ứng dụng của bạn. Bạn có thể định cấu hình tối đa 3 câu lệnh bắt đầu.

Cách thêm và định cấu hình lời nhắc khởi đầu:

1. Trong bảng điều khiển Cloud Console của Google, hãy chuyển đến trang Configuration (Cấu hình) của Chat API:

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

2. Trong phần Tính năng tương tác, hãy tìm Câu lệnh bắt đầu rồi nhấp vào Thêm câu lệnh.

3. Trong trường Thứ hạng (1-3), hãy nhập một số từ 1 đến 3 để chỉ định thứ tự hiển thị.

4. Trong mục Lựa chọn về loại, hãy chọn cách lời nhắc hoạt động:

   • Câu lệnh văn bản: Điền văn bản được xác định trước vào thanh soạn tin khi người dùng nhấp vào khối câu lệnh.
   • Dấu nhắc lệnh: Chạy một lệnh dấu gạch chéo hoặc lệnh nhanh đã đăng ký khi được nhấp vào. Bạn không thể chọn những lệnh yêu cầu đối số bổ sung.

5. Định cấu hình câu lệnh dựa trên lựa chọn loại của bạn:

   • Nếu bạn chọn Câu lệnh dạng văn bản:

     1. Trong phần Tiêu đề, hãy nhập tiêu đề của câu lệnh xuất hiện trên khối văn bản (tối đa 30 ký tự).
     2. Trong phần Văn bản câu lệnh, hãy nhập văn bản được điền sẵn trong thanh soạn tin (tối đa 60 ký tự).
     3. Không bắt buộc: Thêm tiêu đề và văn bản được bản địa hoá cho người dùng bằng các ngôn ngữ khác:
     4. Trong phần Câu lệnh bản địa hoá, hãy nhấp vào Thêm ngôn ngữ.
     5. Trong phần Ngôn ngữ, hãy chọn một ngôn ngữ được hỗ trợ trong trình đơn thả xuống.
     6. Trong Tiêu đề theo ngôn ngữ địa phương, hãy nhập tiêu đề theo ngôn ngữ địa phương (tối đa 30 ký tự).
     7. Trong phần Văn bản câu lệnh đã được bản địa hoá, hãy nhập văn bản câu lệnh đã được bản địa hoá (tối đa 60 ký tự).
     8. Lặp lại để thêm các ngôn ngữ khác nếu cần.

   • Nếu bạn chọn Command Prompt:

     1. Trong phần Lệnh dấu gạch chéo / Lệnh nhanh, hãy chọn lệnh trong trình đơn thả xuống.

6. Nhấp vào Xong, rồi nhấp vào Lưu ở cuối trang.

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

Nếu 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), Google Chat có thể thử lại việc gửi vài lần trong vòng vài phút (nhưng không được đảm bảo). Do đó, ứng dụng Chat có thể nhận được cùng một thông báo vài lần trong một số trường hợp. Nếu yêu cầu hoàn tất thành công nhưng trả về tải trọng thông báo 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 các 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 trò chuyện tương tác sẽ trả lời người dùng bằng một tin nhắn. Ứng dụng Google Chat cũng có thể tra cứu một số thông tin từ nguồn dữ liệu, ghi lại thông tin về sự kiện tương tác hoặc bất kỳ thông tin nào khác. Hành vi xử lý này về cơ bản là những gì xác định ứng dụng Google Chat.

Để phản hồi đồng bộ, một ứ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 nơi xảy ra hoạt động 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 Chat sẽ nhận được một nội dung yêu cầu, đây là tải trọng JSON đại diện cho sự kiện đó. Bạn có thể dùng thông tin này để xử lý một phản hồi. Để xem ví dụ về tải trọng sự kiện, hãy xem Các loại sự kiện tương tác của ứng dụng 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

Các sự kiện tương tác cho phép ứng dụng 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 các hướng dẫn sau:

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

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

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

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

/**
 * 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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

/**
 * 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.
 */
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ề tin nhắn văn bản sau:

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

Đôi khi, các ứng dụng trò chuyện 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 tác vụ bên ngoài không gian nơi sự kiện tương tác được tạo. Ví dụ: một ứng dụng Chat có thể cần phản hồi người dùng sau khi hoàn tất 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 Google Chat API.

Để tạo tin nhắn bằng API Chat, hãy xem phần Tạo tin nhắn. Để xem hướng dẫn về cách sử dụng các phương thức bổ sung của Chat API, hãy xem 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 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
• Tạo trang chủ cho một ứng dụng Chat
• Xác minh yêu cầu của Chat
• Kiểm thử các tính năng tương tác cho ứng dụng Google Chat