Trang này được dịch bởi Cloud Translation API.

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 lượt 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 trình kích hoạt mà các tiện ích bổ sung của Google Workspace sử dụng trong Chat.

Trình 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 @thao tác nhắc hoặc lệnh gạch chéo.

Bảng sau đây cho thấy các điều kiện 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

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. @thao tác nhắc đến ứng dụng Chat trong bất kỳ loại không gian nào. Gửi tin nhắn chứa lệnh dấu gạch chéo 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.	Ứ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. Các ứ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.

Đã 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.
@thao tác nhắc đến ứng dụng Chat trong bất kỳ loại không gian nào.
Gửi tin nhắn chứa lệnh dấu gạch chéo 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.

Ứ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. Các ứ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.

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ả cá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 giá trị 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.

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 một `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.

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 hoạt động 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:

DataActions: Tạo hoặc cập nhật dữ liệu Google Workspace. Để gửi hoặc cập nhật tin nhắn trong Chat, đối tượng phải chứa mã đánh dấu xác định các thay đổi đối với dữ liệu Message, được biểu thị dưới dạng chatDataActionMarkup.
RenderActions: Hiển thị hoặc di chuyển giữa các thẻ trong thông báo và hộp thoại.
basic_authorization_prompt: Nhắc người dùng có thẻ uỷ quyền đăng nhập hoặc xác thực vào một dịch vụ bên ngoài Google. Để biết thông tin chi tiết, hãy xem bài viết Kết nối tiện ích bổ sung của Google Workspace với dịch vụ của bên thứ ba.

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.