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ủ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 trong Google Chat.

Để xây dựng giao diện tương tác cho ứng dụng Chat, bạn sử dụng các thành phần sau:

  • Trình kích hoạt: Cách người dùng Google Chat có thể gọi một ứng dụng Chat, chẳng hạn như thêm ứng dụng đó vào không gian hoặc gửi tin nhắn cho ứng dụng đó.
  • Đối tượng sự kiện: Dữ liệu mà ứng dụng Chat nhận được từ các điều kiện kích hoạt hoặc hoạt động tương tác trên giao diện người dùng.
  • Hành động: Cách ứng dụng Chat có thể phản hồi các hoạt động tương tác, chẳng hạn như gửi tin nhắn hoặc trả về giao diện người dùng dựa trên thẻ.
Ứng dụng Chat nhận được một đối tượng sự kiện từ điều kiện kích hoạt Đã thêm vào không gian
Hình 1: Khi người dùng thêm một ứng dụng Chat vào không gian, trình kích hoạt Đã thêm vào không gian sẽ kích hoạt và gửi một đối tượng sự kiện. Để trả lời bằng một tin nhắn, ứng dụng Chat sẽ xử lý đối tượng sự kiện và trả về một hành động tạo tin nhắn.

Ứng dụng trò chuyện có thể xây dựng và hiển thị giao diện theo những cách sau:

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

Cách hoạt động của các lượt tương tác của người dùng

Khi người dùng tương tác với một ứng dụng Chat, Google Chat sẽ gọi một điểm kích hoạt đã định cấu hình và gửi một đối tượng sự kiện đến điểm cuối hoặc hàm của ứng dụng Chat. Ứng dụng Chat của bạn sẽ xử lý đối tượng sự kiện và có thể trả về một hành động đồng bộ trong vòng 30 giây hoặc phản hồi không đồng bộ bằng API Chat.

Sơ đồ sau đây minh hoạ cách ứng dụng Google Chat xử lý và phản hồi các hoạt động tương tác của người dùng:

Cấu trúc về cách các ứng dụng Google Chat xử lý hoạt động tương tác của người dùng.

Điều kiện kích hoạt

Trình kích hoạt là những cách cụ thể mà người dùng gọi một ứng dụng Chat bằng giao diện người dùng của Chat, chẳng hạn như sử dụng lệnh @đề_cập hoặc lệnh ứng dụng.

Bảng sau đây trình bày các điều kiện kích hoạt của Chat, nội dung mô tả và cách ứng dụng Chat thường phản hồi:

Trigger Mô tả Câu trả lời thông thường
Đã thêm vào không gian

Người dùng thêm ứng dụng Chat vào một không gian hoặc quản trị viên Google Workspace cài đặt ứng dụng Chat trong không gian tin nhắn trực tiếp cho người dùng trong tổ chức của họ. Để tìm hiểu về các ứng dụng Chat do quản trị viên cài đặt, hãy xem bài viết Cài đặt các ứng dụng trên Marketplace trong miền của bạn trong tài liệu Trợ giúp dành cho quản trị viên Google Workspace.

 Ứng dụng Chat sẽ gửi một thông báo giới thiệu 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.
Tin nhắn

Người dùng tương tác với ứng dụng Chat trong một tin nhắn theo một trong những cách sau:

  • Gửi tin nhắn trong không gian tin nhắn trực tiếp (DM) bằng ứng dụng Chat.
  • @đề cập đến ứng dụng Chat trong bất kỳ loại không gian nào.
  • Gửi một tin nhắn có chứa đường liên kết khớp với mẫu URL cho bản xem trước đường liên kết.
  • Nhập văn bản vào trình đơn chọn nhiều mục của một tiện ích selectionInput.
 Ứng dụng Chat sẽ phản hồi dựa trên nội dung của tin nhắn. Ví dụ: một ứng dụng Chat trả lời bằng một tin nhắn, đính kèm thẻ xem trước đường liên kết hoặc đề xuất các mục trong trình đơn chọn nhiều mục.
Đã bị xoá khỏi không gian

Người dùng xoá ứng dụng Chat khỏi không gian hoặc quản trị viên Google Workspace gỡ cài đặt ứng dụng Chat cho người dùng trong tổ chức của họ.

Người dùng không thể xoá các ứng dụng Chat do quản trị viên cài đặt. Nếu người dùng đã cài đặt ứng dụng Chat trước đó, thì ứng dụng Chat vẫn được cài đặt bất kể quản trị viên Google Workspace có cố gắng gỡ cài đặt ứng dụng đó hay không.

 Ứ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á một webhook) và xoá mọi bộ nhớ trong. Ứng dụng Chat không thể trả lời bằng tin nhắn cho điều kiện kích hoạt này vì ứng dụng không còn là thành viên của không gian.
Lệnh ứng dụng

Người dùng gọi một lệnh của ứng dụng Chat (chẳng hạn như lệnh dấu gạch chéo, lệnh nhanh hoặc hành động tin nhắn).

 Ứng dụng Chat phản hồi lệnh. Ví dụ: ứng dụng trả lời bằng một tin nhắn hoặc mở một hộp thoại.
Trang chủ ứng dụng

Người dùng mở thẻ Trang chủ trong không gian tin nhắn trực tiếp (DM) 1:1 bằng ứng dụng Chat hoặc tương tác với một tiện ích trên thẻ trang chủ.

 Ứng dụng Chat trả về một đối tượng RenderActions để đẩy thẻ trang chủ (pushCard) hoặc cập nhật thẻ trang chủ hiển thị (updateCard).

Bạn định cấu hình các điểm cuối hoặc hàm callback cho những điều kiện kích hoạt này trong Google Cloud Console trên trang Cấu hình của Chat API. Để xem hướng dẫn từng bước, hãy xem bài viết Định cấu hình API Google Chat.

Định cấu hình câu lệnh mở đầu

Câu lệnh mở đầ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 bằng ứng dụng của bạn. Bạn có thể định cấu hình tối đa 3 câu lệnh mở đầu.

Cách thêm và định cấu hình câu lệnh mở đầu:

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

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

  2. Trong phần Tính năng tương tác, hãy tìm mục Câu lệnh mở đầ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 phần Chọn loại, hãy chọn cách hoạt động của câu lệnh:

    • Câu lệnh văn bản: Điền sẵ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.
    • Lời nhắc lệnh: Chạy lệnh dấu gạch chéo hoặc lệnh nhanh đã đăng ký khi người dùng nhấp vào. Bạn không thể chọn các 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 văn bản:

      1. Trong phần Tiêu đề, hãy nhập tiêu đề câu lệnh xuất hiện trên khối (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 sử dụng ngôn ngữ khác:
      4. Trong phần Câu lệnh được 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 phần Tiêu đề được bản địa hoá, hãy nhập tiêu đề được bản địa hoá (tối đa 30 ký tự).
      7. Trong phần Localized Prompt text (Văn bản lời nhắc đã bản địa hoá), hãy nhập văn bản lời 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 đến 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), thì Google Chat có thể thử gửi lại một vài lần trong vòng vài phút (nhưng không đảm bảo). Do đó, một ứng dụng Chat có thể nhận được cùng một sự kiện vài lần trong một số trường hợp nhất định. Nếu yêu cầu hoàn tất thành công nhưng trả về tải trọng phản hồi không hợp lệ, thì Google Chat sẽ không thử lại yêu cầu đó.

Đối tượng sự kiện

Ứng dụng Chat nhận được đối tượng sự kiện khi trình kích hoạt Chat chạy hoặc khi người dùng Chat tương tác với giao diện người dùng của ứng dụng Chat (chẳng hạn như nhấp vào nút hoặc gửi hộp thoại). Đối tượng sự kiện cho phép bạn sử dụng dữ liệu tương tác để phản hồi hoặc cập nhật giao diện người dùng.

Vào năm 2025, các ứng dụng Google Chat đã được mở rộng để hỗ trợ các sự kiện của tiện ích bổ sung. Đây là chế độ mặc định cho các ứng dụng Chat mới kể từ tháng 7 năm 2025. Trong toàn bộ tài liệu về Chat, sự kiện tiện ích bổ sung là loại sự kiện chuẩn được trình bày trong các hướng dẫn và mã mẫu. Tài liệu về các sự kiện trong Chat (đối với các ứng dụng Chat không phải là tiện ích bổ sung của Google Workspace) được tách thành các phần thu gọn (ví dụ: Ứng dụng Chat không phải là tiện ích bổ sung: Nhận và phản hồi các sự kiện tương tác).

Xác định loại sự kiện và loại phản hồi

Khi ứng dụng Chat nhận được một đối tượng sự kiện, cấu trúc của tải trọng và cách bạn phản hồi sẽ phụ thuộc vào việc ứng dụng Chat của bạn có được định cấu hình làm tiện ích bổ sung của Google Workspace hay không.

Để xác nhận loại đối tượng sự kiện mà ứng dụng của bạn nhận được và cách ứng dụng phản hồi, hãy kiểm tra cấu hình của ứng dụng bằng bảng sau:

Loại ứng dụng Nhận sự kiện của tiện ích bổ sung
(Mặc định cho các ứng dụng mới được tạo sau tháng 7 năm 2025)		 Nhận sự kiện trong Chat
(Mặc định trước đây, trước tháng 7 năm 2025)
Ứng dụng Apps Script
Kiểm tra tệp kê khai (appsscript.json)		 Đối tượng chat được định cấu hình bên trong addOns: 
{
  "addOns": {
    "chat": {}
  }
}
 		Đối tượng chat được định cấu hình ở gốc của tệp kê khai: 
{
  "chat": {}
}
Các ứng dụng khác
Kiểm tra trang Cấu hình Google Chat API		 Hộp đánh dấu "Xây dựng ứng dụng Chat này dưới dạng tiện ích bổ sung của Google Workspace" đã được chọn. Hộp đánh dấu "Xây dựng ứng dụng Chat này dưới dạng một tiện ích bổ sung của Google Workspace" chưa được chọn.
Nơi tìm tài liệu Trong các hướng dẫn và mã mẫu

Tài liệu tham khảo về sự kiện: Đối tượng sự kiện của tiện ích bổ sung		 Các phần được thu gọn (ví dụ: Ứng dụng Chat không phải là tiện ích bổ sung: Nhận và phản hồi các sự kiện tương tác)

Tài liệu tham khảo về sự kiện: Sự kiện tương tác của API Chat
Cách phản hồi Trả về một hành động, chẳng hạn như DataActions hoặc RenderActions.
Xem cách phản hồi bằng một hành động		 Trả về tài nguyên Message.
Xem cách trả lời bằng tin nhắn

Phần tải trọng của đối tượng sự kiện

Mỗi đối tượng sự kiện của tiện ích bổ sung đều bao gồm một commonEventObject có thông tin chi tiết về máy chủ và nền tảng (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters và formInputs) và một đối tượng chat chứa bối cảnh dành riêng cho Chat:

  • Đối với điều kiện kích hoạt Trang chủ ứng dụng (khi người dùng mở thẻ Trang chủ trong tin nhắn trực tiếp 1:1 với ứng dụng Chat), đối tượng chat chứa chat.user và chat.eventTime mà không có trường hợp nhất payload. Khi người dùng nhấp vào một nút trong thẻ trang chủ, đối tượng sự kiện sẽ bao gồm chat.buttonClickedPayload cùng với commonEventObject.parameters (và commonEventObject.formInputs nếu thẻ chứa dữ liệu đầu vào của biểu mẫu).
  • Đối với các hoạt động tương tác trong không gian và tin nhắn (Đã thêm vào không gian, Tin nhắn, Đã xoá khỏi không gian, Lệnh ứng dụng hoặc các hoạt động tương tác với nút và tiện ích), đối tượng chat bao gồm chat.user, chat.space, chat.eventTime và tải trọng tương tác tương ứng:
    • messagePayload: Chứa space, message và configCompleteRedirectUri khi người dùng gửi tin nhắn.
    • addedToSpacePayload: Chứa space, interactionAdd và configCompleteRedirectUri khi ứng dụng Chat được thêm vào một không gian.
    • removedFromSpacePayload: Chứa space khi ứng dụng Chat bị xoá khỏi một không gian.
    • buttonClickedPayload: Chứa space, message, isDialogEvent và dialogEventType khi người dùng nhấp vào một nút trên thẻ hoặc hộp thoại.
    • widgetUpdatedPayload: Chứa space khi người dùng tương tác với một tiện ích, chẳng hạn như nhập vào trình đơn nhiều lựa chọn có nguồn dữ liệu bên ngoài.
    • appCommandPayload: Chứa space, message, appCommandMetadata, isDialogEvent, dialogEventType và configCompleteRedirectUri khi người dùng gọi một lệnh của ứng dụng.

Để tìm hiểu về các đối tượng sự kiện của tiện ích bổ sung trong Chat và các ứng dụng khác của Google Workspace, hãy xem bài viết Đối tượng sự kiện.

Đưa ra câu trả lời

Phần này giải thích cách ứng dụng Chat sử dụng hành động để phản hồi đồng bộ với các hoạt động tương tác của người dùng.

Để phản hồi bằng một hành động, ứng dụng Chat phải phản hồi trong vòng 30 giây và phản hồi đó phải áp dụng cho không gian nơi diễn ra hoạt động tương tác. Những phản hồi đồng bộ này không yêu cầu xác thực. Nếu ứng dụng Chat của bạn cần hơn 30 giây hoặc cần hoạt động bên ngoài không gian, hãy thiết lập quy trình xác thực và phản hồi không đồng bộ bằng API Google Chat.

Để phản hồi các hoạt động tương tác của người dùng một cách đồng bộ, ứng dụng Chat của bạn sẽ xử lý đối tượng sự kiện đến và trả về một trong các đối tượng JSON sau:

  • DataActions: Tạo hoặc cập nhật tin nhắn trò chuyện (CreateMessageAction, UpdateMessageAction) hoặc đính kèm bản xem trước đường liên kết (UpdateInlinePreviewAction) bằng chatDataActionMarkup.
  • RenderActions: Tạo, cập nhật hoặc đóng trang chủ hoặc hộp thoại (pushCard, updateCard, endNavigation: "CLOSE_DIALOG") hoặc cung cấp đề xuất nhập dữ liệu động cho trình đơn chọn nhiều mục (modifyCard).
  • AuthorizationError: Nhắc người dùng bằng thẻ uỷ quyền cơ bản (basic_authorization_prompt) để đăng nhập hoặc xác thực với một dịch vụ bên ngoài.

Bảng sau đây cho biết cách ứng dụng Chat có thể phản hồi bằng các hành động. Ứng dụng Chat có thể trả về trực tiếp các đối tượng JSON hoặc tạo phản hồi bằng cách sử dụng AddOnResponseService và CardService của Apps Script.

Câu trả lời của ứng dụng Chat Hành động bắt buộc để trả về (JSON) Thao tác bắt buộc để trả về (Apps Script)
Gửi tin nhắn hoặc cập nhật tin nhắn. DataActions (createMessageAction hoặc updateMessageAction) DataActionsResponse
Xem trước đường liên kết trong tin nhắn mà người dùng Chat gửi trong không gian. DataActions (updateInlinePreviewAction) DataActionsResponse
Hiển thị hoặc cập nhật trang chủ trong thẻ Trang chủ của tin nhắn trực tiếp. RenderActions (pushCard hoặc updateCard) ActionResponse
Mở, cập nhật hoặc đóng hộp thoại. RenderActions (pushCard, updateCard hoặc endNavigation: "CLOSE_DIALOG") ActionResponse
Để thu thập thông tin từ thẻ hoặc hộp thoại, hãy đề xuất các mục lựa chọn dựa trên nội dung người dùng nhập vào trình đơn nhiều lựa chọn. RenderActions (modifyCard) ActionResponse
Yêu cầu cấu hình hoặc uỷ quyền cho một dịch vụ bên ngoài. AuthorizationError (basic_authorization_prompt) AuthorizationException

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

Ứng dụng trò chuyện có thể phản hồi bằng tin nhắn cho bất kỳ điểm kích hoạt hoặc hoạt động tương tác nào sau đây:

  • Trình kích hoạt tin nhắn, chẳng hạn như khi người dùng đề cập bằng @hoặc gửi tin nhắn trực tiếp cho một ứng dụng Chat.
  • Trình kích hoạt Đã thêm vào không gian, chẳng hạn như khi người dùng cài đặt ứng dụng Chat từ Google Workspace Marketplace hoặc thêm ứng dụng đó vào một không gian.
  • Trình kích hoạt lệnh trong ứng dụng, chẳng hạn như khi người dùng gọi một lệnh dấu gạch chéo hoặc lệnh nhanh.
  • Số lượt nhấp vào nút trên thẻ trong tin nhắn hoặc hộp thoại. Ví dụ: khi người dùng nhập thông tin và nhấp vào nút gửi.

Ứng dụng trò chuyện có thể bao gồm bất kỳ nội dung nào sau đây trong tin nhắn:

  • Văn bản chứa siêu liên kết, lượt đề cập bằng @ và biểu tượng cảm xúc. Xem phần Định dạng thư.
  • Một hoặc nhiều thẻ, có thể xuất hiện trong một thông báo hoặc mở trong một cửa sổ mới dưới dạng hộp thoại. Xem bài viết Tạo thẻ cho ứng dụng Google Chat.
  • Một hoặc nhiều tiện ích bổ sung, là các nút xuất hiện sau văn bản hoặc thẻ bất kỳ trong tin nhắn.

Để trả lời bằng một tin nhắn, hãy trả về DataActions bằng một đối tượng CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Thay thế MESSAGE bằng tài nguyên Message trong API Chat.

Trong ví dụ sau, một ứng dụng Chat tạo và gửi tin nhắn văn bản giới thiệu bất cứ khi nào ứng dụng đó được thêm vào một không gian bằng cách phản hồi trình kích hoạt Đã thêm vào không gian bằng DataActions:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      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`.'
    }}}}});
  }
};

Python

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.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "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`.'
      }}
    }}})

Java

@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 GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", 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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    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:

Ví dụ về thông báo hướng dẫn.

Cập nhật tin nhắn

Ứng dụng trò chuyện cũng có thể cập nhật tin nhắn mà ứng dụng gửi. Ví dụ: một Ứng dụng trò chuyện có thể cập nhật tin nhắn sau khi người dùng gửi hộp thoại hoặc nhấp vào một nút trên thẻ trong tin nhắn.

Để cập nhật tin nhắn của ứng dụng Chat nhằm phản hồi một lượt tương tác, hãy trả về DataActions bằng UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Thay thế MESSAGE bằng tài nguyên Message trong API Chat.

Ứng dụng Chat cũng có thể cập nhật tin nhắn do người dùng gửi để đính kèm thẻ xem trước đường liên kết bằng updateInlinePreviewAction. Để biết thông tin chi tiết, hãy xem bài viết Xem trước đường liên kết.

Phản hồi không đồng bộ bằng API Google Chat

Thay vì trả về một hành động đồng bộ, ứng dụng Chat có thể cần gọi API Google Chat để phản hồi một lượt tương tác hoặc gửi tin nhắn chủ động. Ví dụ: ứng dụng Chat phải gọi API Google Chat để thực hiện bất kỳ thao tác nào sau đây:

  • Phản hồi một lượt tương tác sau 30 giây (chẳng hạn như sau khi hoàn tất một tác vụ chạy trong thời gian dài).
  • Gửi tin nhắn theo lịch hoặc gửi thông báo về các thay đổi đối với tài nguyên bên ngoài.
  • Thực hiện các tác vụ bên ngoài không gian nơi diễn ra hoạt động tương tác.
  • Thực hiện các tác vụ trong Chat không có sẵn dưới dạng hành động đồng bộ, chẳng hạn như liệt kê không gian hoặc thêm thành viên vào không gian.
  • Thực hiện các thao tác thay mặt cho người dùng Chat (yêu cầu xác thực người dùng).

Khi phản hồi một lượt tương tác sau 30 giây, để tránh thông báo lỗi dành cho người dùng cho biết ứng dụng Chat của bạn không phản hồi, bạn phải xác nhận đã nhận được đối tượng sự kiện trong vòng 30 giây bằng cách trả về một phản hồi trống:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Để gửi tin nhắn bằng API Chat, hãy thiết lập quy trình xác thực và gọi phương thức spaces.messages.create. Để biết các bước thực hiện, hãy xem phần Gửi tin nhắn. Để xem hướng dẫn về cách sử dụng các phương thức khác của API Chat, hãy xem Tổng quan về API Chat.

Ứng dụng Chat không phải là tiện ích bổ sung: Nhận và phản hồi các hoạt động tương tác của người dùng

Các ứng dụng Chat không phải là tiện ích bổ sung của Google Workspace sẽ nhận được Sự kiện tương tác của API Chat (Event) thay vì Đối tượng sự kiện của tiện ích bổ sung Google Workspace (EventObject), và phản hồi bằng cách trả về một tài nguyên Message thay vì một hành động.

Để nâng cấp một ứng dụng Chat không phải là tiện ích bổ sung lên khung tiện ích bổ sung của Google Workspace, hãy xem bài viết Chuyển đổi ứng dụng Google Chat thành tiện ích bổ sung của Google Workspace.

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

Đối với mỗi loại hoạt động tương tác của người dùng, Google Chat sẽ gửi cho ứng dụng Chat không phải là tiện ích bổ sung một đối tượng Event có loại được biểu thị bằng trường eventType:

Tương tác với người dùng eventType Phản hồi thông thường từ một ứng dụng Chat không phải là tiện ích bổ sung
Người dùng nhắn tin cho một ứng dụng Chat. Ví dụ: @đề cập đến ứng dụng Chat hoặc sử dụng lệnh dấu gạch chéo. MESSAGE Ứng dụng Chat sẽ phản hồi dựa trên nội dung của tin nhắn. Ví dụ: một ứng dụng Chat trả lời lệnh dấu gạch chéo /about bằng một tin nhắn giải thích các việc cần làm mà ứng dụng Chat có thể thực hiện.
Người dùng thêm một ứng dụng Chat vào không gian. ADDED_TO_SPACE Ứng dụng Chat sẽ gửi một thông báo giới thiệu 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.
Người dùng xoá một ứng dụng 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á một webhook) và dọn dẹp mọi 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 biểu mẫu từ 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.
Người dùng gọi một lệnh bằng cách sử dụng lệnh nhanh. APP_COMMAND Ứng dụng Chat sẽ phản hồi dựa trên lệnh được gọi. Ví dụ: một ứng dụng Chat trả lời lệnh Giới thiệu bằng một tin nhắn giải thích các việc mà ứng dụng Chat có thể làm.

Để xem tất cả sự kiện tương tác được hỗ trợ và tải trọng JSON mẫu, hãy xem bài viết Các loại sự kiện tương tác của ứng dụng Chat và tài liệu tham khảo EventType.

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

Nếu ứng dụng Chat không phải là tiện ích bổ sung 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:

  • Trường isDialogEvent được đặt thành true.
  • DialogEventType (REQUEST_DIALOG, SUBMIT_DIALOG hoặc CANCEL_DIALOG) cho biết 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 hay không.

Định cấu hình một ứng dụng Chat không phải là tiện ích bổ sung để nhận sự kiện tương tác

  1. Trong Google Cloud Console, hãy chuyển đến trang Cấu hình của API Chat:

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

  2. Trong phần Tính năng tương tác, hãy bỏ đánh dấu Tạo ứng dụng Chat này dưới dạng tiện ích bổ sung của Google Workspace, rồi định cấu hình Chức năng, một điểm cuối Cài đặt kết nối (URL điểm cuối HTTP, Apps Script, tên chủ đề Cloud Pub/Sub hoặc Dialogflow), Lệnh, Câu lệnh mở đầu, Bản xem trước đường liên kết và Chế độ hiển thị.

  3. Nhấp vào Lưu.

Trả lời bằng tin nhắn trong một ứng dụng Chat không phải là tiện ích bổ sung

Để phản hồi đồng bộ trong một ứng dụng Chat không phải là tiện ích bổ sung, hãy trả về trực tiếp một đối tượng Message. Ví dụ sau đây phản hồi một sự kiện tương tác ADDED_TO_SPACE bằng một tin nhắn văn bản:

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

Python

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({})

Java

@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();
    }
  }
}

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.
 */
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`.'
  };
}