Tạo giao diện Google Chat

Trang này cung cấp thông tin tổng quan về cách tạo giao diện người dùng (UI) cho các tiện ích bổ sung của Google Workspace mở rộng Google Chat.

Để tạo giao diện cho các ứng dụng Chat, bạn có thể dùng các thành phần bổ sung sau:

  • Triggers (Điều kiện kích hoạt): Các cách mà 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 một không gian hoặc gửi tin nhắn cho ứng dụng đó.
  • Đối tượng sự kiện: Dữ liệu mà Các ứng dụng trò chuyện 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 các ứ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ừ mộ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 một 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. Để phản hồ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 thao tác tạo tin nhắn.

Các ứng dụng trò chuyện có thể tạo và hiển thị thẻ trong các giao diện sau:

  • Tin nhắn có thể chứa văn bản, thẻ tĩnh hoặc thẻ tương tác và nút.
  • Trang chủ xuất hiện trong thẻ Trang chủ của tin nhắn trực tiếp 1:1 với ứng dụng Chat.
  • Hộp thoại là những thẻ mở ra trong một cửa sổ mới và thường nhắc người dùng gửi thông tin.
  • Thông tin xem trước đường liên kết là những thẻ xem trước thông tin về một dịch vụ bên ngoài.

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

Phần này giải thích các điều kiện kích hoạt mà tiện ích bổ sung Google Workspace sử dụng trong Chat.

Điều kiện 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 Chat, chẳng hạn như dùng tính năng @đề cập hoặc lệnh của ứng dụng.

Bảng sau đây cho thấy các câu lệnh kích hoạt Chat, nội dung mô tả và cách các ứ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 phần 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 về 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 theo một trong những cách sau:

  • Gửi tin nhắn trong một 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 mọi loại không gian.
  • Gửi một thông báo có chứa đường liên kết khớp với mẫu URL cho bản xem trước của đườ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 sẽ trả lời lệnh dấu gạch chéo /about bằng một tin nhắn giải thích những việc mà ứng dụng Chat có thể làm.
Đã xoá khỏi không gian

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

Người dùng không thể xoá các ứng dụng nhắn tin do quản trị viên cài đặt. Nếu trước đó người dùng đã cài đặt ứng dụng Chat, 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 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á webhook) và xoá mọi bộ nhớ trong. Các ứng dụng trò chuyện không thể phản hồi bằng tin nhắn cho sự kiện kích hoạt này vì không còn là thành viên của không gian.
Lệnh ứng dụng

Người dùng sử dụng lệnh của ứng dụng Chat.

 Ứng dụng Chat sẽ phản hồi lệnh này. Ví dụ: trả lời bằng một tin nhắn hoặc mở một hộp thoại.
Trang chủ của ứ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 với ứ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ủ được hiển thị (updateCard).

Không giống như các tiện ích bổ sung khác, bạn phải định cấu hình mọi hàm gọi lại cho các sự kiện kích hoạt này bằng Google Chat API. Để được hướng dẫn, hãy xem phần Định cấu hình ứng dụng trò chuyện.

Để phản hồi một điều kiện kích hoạt, hãy xem các hướng dẫn sau:

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

Các ứng dụng trò chuyện nhận được các đối tượng sự kiện khi một Trình kích hoạt trò chuyện chạy hoặc khi người dùng Trò chuyện tương tác với giao diện người dùng của ứng dụng Trò chuyện (chẳng hạn như nhấp vào một nút). Đố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.

Tải trọng đối tượng sự kiện

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

  • Đối với một sự kiện kích hoạt Trang chủ của ứ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 sẽ chứa chat.user và chat.eventTime mà không có trường payload hợp nhất. Khi người dùng nhấp vào một nút trong thẻ trang chủ, đối tượng sự kiện cũng bao gồm 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 (Được thêm vào không gian, Tin nhắn, Bị xoá khỏi không gian, Lệnh của ứ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, addedToSpacePayload, removedFromSpacePayload, buttonClickedPayload, widgetUpdatedPayload hoặc appCommandPayload).

Để tìm hiểu về cách xử lý các đối tượng sự kiện, hãy xem các hướng dẫn sau:

Để 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 phần Đối tượng sự kiện.

Thao tác bạn có thể thực hiện trong cuộc trò chuyện

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

Để phản hồi bằng một thao tác bổ sung, ứ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 phải thiết lập quy trình xác thực và gọi API Google Chat để phản hồi.

Các ứng dụng trò chuyện có thể xử lý và phản hồi các hoạt động tương tác theo nhiều cách. Trong nhiều trường hợp, các ứng dụng Chat sẽ trả lời bằng một tin nhắn. Các ứng dụng trò chuyện 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 đối tượng sự kiện 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 các hoạt động tương tác của người dùng, các ứng dụng trò chuyện phải xử lý đối tượng sự kiện tương ứng và trả về một trong các đối tượng JSON sau:

Bảng sau đây cho biết cách các ứng dụng Chat có thể phản hồi bằng các thao tác. Các ứng dụng Chat có thể trả về các đối tượng JSON hoặc tạo phản hồi bằng AddOnResponseService của Apps Script.

Câu trả lời của ứng dụng trong Chat Hành động bắt buộc để trả về (JSON) Việc cần làm để trả về (Apps Script)
Gửi hoặc cập nhật tin nhắn. DataActions DataActionsResponse
Hiển thị hoặc cập nhật trang chủ trong thẻ Trang chủ của một tin nhắn trực tiếp. RenderActions ActionResponse
Mở, cập nhật hoặc đóng một hộp thoại. RenderActions 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 mà người dùng nhập vào một trình đơn chọn nhiều mục. RenderActions ActionResponse
Xem trước đường liên kết trong tin nhắn mà người dùng Chat gửi trong một không gian. DataActions DataActionsResponse

Trả lời bằng API Google Chat

Thay vì trả về một thao tác của tiện ích bổ sung, các ứng dụng Chat có thể cần sử dụng Google Chat API để phản hồi một lượt tương tác. Ví dụ: Các ứng dụng Chat phải gọi Google Chat API để 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.
  • Thực hiện các thao tác bên ngoài không gian diễn ra hoạt động tương tác.
  • Thực hiện các việc cần làm trong Chat không có sẵn dưới dạng hành động bổ sung. Ví dụ: liệt kê những không gian mà người dùng hoặc ứng dụng Chat là thành viên, hoặc thêm người dùng vào không gian.
  • Thực hiện các tác vụ 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 sự kiện tương tác sau 30 giây, để tránh thông báo lỗi mà người dùng nhìn thấy 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 một sự kiện tương tác trong vòng 30 giây bằng cách gửi một phản hồi trống, như minh hoạ ở đây:

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

Để tìm hiểu về cách xác thực và gọi Chat API, hãy xem bài viết Tổng quan về Chat API.