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.

Trong Google Chat, các tiện ích bổ sung sẽ xuất hiện với người dùng dưới dạng ứng dụng Google Chat. Để tìm hiểu thêm, hãy xem bài viết Tổng quan về việc mở rộng Google Chat.

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

  • Trình kích hoạt: Các 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 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à ứ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.
  • Thao tác: Các cách mà ứng dụng Chat có thể phản hồi các lượt 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 đố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 một không gian, điều kiện 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 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.

Ứ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 tương tác và các nút.
  • Hộp thoại là các thẻ mở trong một cửa sổ mới và thường nhắc người dùng gửi thông tin.
  • Bản xem trước đường liên kết là các 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à các tiện ích bổ sung của 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 ứng dụng Chat bằng giao diện người dùng Chat, chẳng hạn như sử dụng tính năng @thắc mắc hoặc lệnh ứng dụng.

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

Kích hoạt Mô tả Phản hồ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 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 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 nhiều lựa chọn của tiện ích selectionInput.
 Ứng dụng Chat phản hồ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.
Đã 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 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 sẽ 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. Ứng dụng trò chuyện không thể phản hồi bằng tin nhắn đối với điều kiện kích hoạt này vì chúng 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 nhanh hoặc lệnh dấu gạch chéo trong ứng dụng Chat.

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

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

Để 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

Phần này xác định và giải thích tất cả các phần tử của đối tượng sự kiện Chat. Để tìm hiểu thêm, hãy xem phần Đối tượng sự kiện.

Đối tượng sự kiện
commonEventObject object (CommonEventObject)
Một đối tượng chứa thông tin chung cho tất cả đối tượng sự kiện, bất kể ứng dụng lưu trữ.
chat object (Chat)
Một đối tượng chứa tất cả thông tin về các lượt tương tác trong Chat.

Chat (Trò chuyện)

Chat (Trò chuyện)
chat.user object (User)
Người dùng Chat đã tương tác với ứng dụng Chat.
chat.space object (Space)
Không gian Chat nơi người dùng tương tác với ứng dụng Chat.
chat.eventTime

string (Timestamp format)

Thời điểm xảy ra lượt tương tác.

Trường hợp hợp nhất payload.

payload chỉ có thể là một trong những loại sau:
chat.messagePayload

object (MessagePayload)

Tải trọng mà ứng dụng Chat nhận được từ trình kích hoạt Tin nhắn.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Tải trọng mà các ứng dụng Chat nhận được từ trình kích hoạt Đã thêm vào không gian.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Trọng tải mà ứng dụng Chat nhận được từ trình kích hoạt Bị xoá khỏi không gian.
chat.buttonClickedPayload

object (ButtonClickedPayload)

Gói dữ liệu mà ứng dụng Chat nhận được khi người dùng nhấp vào một nút trong tin nhắn hoặc thẻ. Nếu người dùng nhấp vào một nút để gửi thông tin, thì đối tượng commonEventObject.formInputs sẽ chứa các giá trị được thu thập từ người dùng. Để biết thông tin chi tiết, hãy xem phần Thu thập thông tin từ người dùng Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

Trọng tải mà ứng dụng Chat nhận được khi người dùng nhập văn bản vào trình đơn nhiều lựa chọn của tiện ích selectionInput. Các ứng dụng trò chuyện có thể sử dụng đối tượng sự kiện này để điền các mục được đề xuất từ một nguồn dữ liệu động. Ví dụ: để điền sẵn các trường hợp hỗ trợ từ một nguồn dữ liệu bên ngoài, ứng dụng Chat có thể truy vấn nguồn dữ liệu dựa trên nội dung người dùng nhập vào trình đơn, sau đó trả về mọi trường hợp hỗ trợ phù hợp dưới dạng các mục có thể chọn.

Đối tượng CommonEventObject.parameters['autocomplete_widget_query'] chứa giá trị chuỗi mà người dùng nhập vào trình đơn.

chat.appCommandPayload

object (AppCommandPayload)

Trọng tải mà ứng dụng Chat nhận được khi người dùng sử dụng một lệnh trong ứng dụng Chat.

Dung lượng

Tuỳ thuộc vào loại tương tác, sự kiện sẽ chứa một tải trọng với một hoặc nhiều tài nguyên Chat API.

Trọng tải thông báo
MessagePayload
chat.messagePayload.message object (Message)
Tin nhắn trong Chat đã kích hoạt sự kiện.
chat.messagePayload.space object (Space)
Phòng Chat mà người dùng đã gửi tin nhắn gọi ra ứng dụng Chat.

Đã thêm vào tải trọng không gian
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Không gian Chat mà người dùng đã thêm hoặc cài đặt ứng dụng Chat.

Khi quản trị viên cài đặt các ứng dụng Chat, trường space.adminInstalled sẽ được đặt thành true.

chat.addedToSpacePayload.interactionAdd boolean
Liệu người dùng có thêm ứng dụng Chat vào một không gian bằng tin nhắn hay không. Ví dụ: @thao tác nhắc đến ứng dụng Chat hoặc sử dụng lệnh gạch chéo. Nếu true, Chat sẽ gửi một đối tượng sự kiện khác với messagePayload chứa thông tin về tin nhắn.

Đã xoá khỏi tải trọng không gian
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
Không gian Chat mà người dùng đã xoá hoặc gỡ cài đặt ứng dụng Chat.

Khi quản trị viên gỡ cài đặt ứng dụng Chat, trường space.adminInstalled sẽ được đặt thành false.

Trọng tải của lượt nhấp vào nút
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Tin nhắn Chat chứa nút mà người dùng đã nhấp vào.
chat.buttonClickedPayload.space object (Space)
Phòng Chat nơi người dùng nhấp vào một nút trong tin nhắn của ứng dụng Chat.
chat.buttonClickedPayload.isDialogEvent boolean
Liệu người dùng có nhấp vào nút để tương tác với hộp thoại hay không.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Nếu isDialogEvent là true, thì loại tương tác trong hộp thoại.

Enum DialogEventType.

Giá trị của dialogEventType chỉ có thể là một trong những giá trị sau:
TYPE_UNSPECIFIED Giá trị mặc định. Không xác định.
REQUEST_DIALOG Người dùng yêu cầu một hộp thoại. Ví dụ: họ sử dụng lệnh dấu gạch chéo hoặc nhấp vào một nút trong thư.
SUBMIT_DIALOG Người dùng nhấp vào một thành phần tương tác trong hộp thoại. Ví dụ: người dùng điền thông tin vào một hộp thoại và nhấp vào một nút để gửi thông tin.

Tải trọng đã cập nhật của tiện ích
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Phòng Chat nơi diễn ra hoạt động tương tác.

Tải trọng lệnh ứng dụng
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Siêu dữ liệu về lệnh mà người dùng đã sử dụng và cách họ kích hoạt lệnh đó.
chat.appCommandPayload.space object (Space)
Phòng Chat mà người dùng đã sử dụng lệnh.
chat.appCommandPayload.thread object (Thread)
Nếu lượt tương tác xảy ra trong một luồng, thì luồng Chat mà người dùng đã sử dụng lệnh.
chat.appCommandPayload.message object (Message)
Tin nhắn mà người dùng gửi bằng lệnh dấu gạch chéo.
chat.appCommandPayload.configCompleteRedirectUri string
Nếu lệnh cần được uỷ quyền hoặc định cấu hình, thì URL sẽ chuyển hướng người dùng đến sau khi họ hoàn tất quy trình bên ngoài Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Liệu lệnh có mở một hộp thoại hay không.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Loại tương tác với hộp thoại.

Enum DialogEventType.

Giá trị của dialogEventType chỉ có thể là một trong những giá trị sau:
TYPE_UNSPECIFIED Giá trị mặc định. Không xác định.
REQUEST_DIALOG Người dùng yêu cầu một hộp thoại. Ví dụ: họ sử dụng lệnh dấu gạch chéo hoặc nhấp vào một nút trong thư.
SUBMIT_DIALOG Người dùng nhấp vào một thành phần tương tác trong hộp thoại. Ví dụ: người dùng điền thông tin vào một hộp thoại và nhấp vào một nút để gửi thông tin.
Siêu dữ liệu lệnh trong ứng dụng
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

Mã lệnh.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Loại lệnh.

Enum AppCommandType.

Giá trị của AppCommandType chỉ có thể là một trong những giá trị sau:
APP_COMMAND_TYPE_UNSPECIFIED Giá trị mặc định. Không xác định.
SLASH_COMMAND Người dùng sử dụng lệnh này bằng cách gửi một thông báo bắt đầu bằng dấu gạch chéo /.

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 ứng dụng Chat có thể sử dụng các thao tác bổ sung để phản hồi các lượt tương tác của người dùng.

Để phản hồi bằng một hành động 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 diễn ra lượt tương tác. Nếu không, ứng dụng Chat phải thiết lập tính năng xác thực và gọi API Google Chat để phản hồi.

Ứng dụng trò chuyện có thể xử lý và phản hồi các lượt tương tác theo nhiều cách. Trong nhiều trường hợp, ứng dụng Chat sẽ trả lời bằng một tin nhắn. Ứ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. Về cơ bản, hành vi xử lý này là yếu tố xác định ứng dụng Google Chat.

Để phản hồi các lượt tương tác của người dùng, ứng dụng Chat 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:

Phản hồi mong muốn của ứng dụng Chat Hành động bắt buộc để trả lại
Gửi hoặc cập nhật thông báo. DataActions
Mở, cập nhật hoặc đóng hộp thoại. RenderActions
Để thu thập thông tin từ mộ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
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

Trả lời bằng API Google Chat

Thay vì trả về một thao tác bổ sung, ứng dụng Chat có thể cần sử dụng API Google Chat để phản hồi một lượt tương tác. Ví dụ: các ứ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.
  • Thực hiện việc cần làm bên ngoài không gian diễn ra hoạt động tương tác.
  • Thực hiện các thao tác trong Chat không có sẵn dưới dạng hành động bổ sung. Ví dụ: liệt kê các 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.
  • Thay mặt người dùng Chat thực hiện các tác vụ (yêu cầu xác thực người dùng).

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