Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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.

Để tạo giao diện tương tác cho các ứng dụng Chat, bạn có thể dùng các thành phần 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ác cách mà ứng dụng Chat có thể phản hồi 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 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 trong Chat có thể tạo và hiển thị giao diện theo những cách sau:

Tin nhắn có thể chứa văn bản, thẻ tĩnh hoặc thẻ tương tác và các nút phụ kiện.
Trang chủ (Trang chủ của ứng dụng) 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.
Bản 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 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 và định cấu hình API Google Chat.

Cách hoạt động của hoạt động 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 trình 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 xử lý đối tượng sự kiện và có thể trả về một thao tác đồng bộ trong vòng 30 giây hoặc phản hồi không đồng bộ bằng Chat API.

Sơ đồ sau đây minh hoạ cách các ứng dụng Google Chat xử lý và phản hồi 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ý lượt tương tác của người dùng.

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

Đ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 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 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 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 một trình đơn chọn nhiều mục.
Đã 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 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á 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 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 thao tác trên tin nhắn).	Ứng dụng Chat sẽ phản hồi lệnh này. Ví dụ: ứng dụng sẽ 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`).

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 Cloud Console trên trang Cấu hình Chat API. Để biết hướng dẫn từng bước, hãy xem phần Định cấu hình API 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:

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
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.
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ị.
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.
Đị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.
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 đó, trong một số trường hợp, ứng dụng Chat có thể nhận được cùng một sự kiện vài lần. Nếu yêu cầu hoàn tất thành công nhưng trả về một 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

Các ứng dụng trò chuyện nhận đượ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 hoặc gửi một 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.

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

Mỗi đối tượng sự kiện Chat đều có một commonEventObject với thông tin chi tiết về máy chủ lưu trữ và nền tảng (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters 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 sẽ bao gồm chat.buttonClickedPayload cùng với commonEventObject.parameters (và commonEventObject.formInputs nếu thẻ chứa các thành phần đầ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 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 sẽ 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 một trình đơn chọn nhiều mục 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 ứ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 phần Đối tượng sự kiện.

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

Phần này giải thích cách các ứng dụng Chat sử dụng hành động để phản hồi đồng bộ 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, ứ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 xảy 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 Google Chat API.

Để 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 các đề xuất nhập độ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ào một dịch vụ bên ngoài.

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ề 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 trong Chat	Hành động bắt buộc để trả về (JSON)	Việc cần làm để trả về (Apps Script)
Gửi tin nhắn hoặc chỉnh sửa 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 một không gian.	`DataActions` (`updateInlinePreviewAction`)	`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` (`pushCard` hoặc `updateCard`)	`ActionResponse`
Mở, cập nhật hoặc đóng một 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 một trình đơn chọn nhiều mục.	`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

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

Tin nhắn kích hoạt, chẳng hạn như khi người dùng @đề cập hoặc nhắn tin trực tiếp cho một ứng dụng Chat.
Được 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 này vào một không gian.
Trình kích hoạt lệnh ứng dụng, chẳng hạn như khi người dùng gọi 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 một tin nhắn:

Văn bản có chứa siêu liên kết, @đề cập 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 phần Tạo thẻ cho các ứ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 bất kỳ văn bản hoặc thẻ nào trong một 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 một tài nguyên Message từ API Chat.

Trong ví dụ sau, một ứng dụng Chat sẽ tạo và gửi tin nhắn văn bản giới thiệu mỗi khi ứng dụng được thêm vào một không gian bằng cách phản hồi sự kiện kích hoạt Được 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 tham gia.

Cập nhật tin nhắn

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

Để cập nhật mộ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 một tài nguyên Message từ API Chat.

Các ứng dụng nhắn tin 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 cách sử dụng updateInlinePreviewAction. Để biết thông tin chi tiết, hãy xem phần Xem trước đường liên kết.

Trả lời không đồng bộ bằng Google Chat API

Thay vì trả về một thao tác đồng bộ, các ứng dụng Chat có thể cần gọi Google Chat API để phản hồi một lượt tương tác hoặc gửi tin nhắn chủ động. 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 hoạt động tương tác sau 30 giây (chẳng hạn như sau khi hoàn tất một tác vụ mất nhiều thời gian).
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 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 thao tác trong Chat không có sẵn dưới dạng các thao tác đồng bộ, chẳng hạn như liệt kê không gian hoặc thêm thành viên vào một không gian.
Thực hiện các tác vụ thay mặt cho người dùng Chat (cần có quy trình 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, 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 bổ sung của Chat API, hãy xem Tổng quan về Chat API.

Ứng dụng nhắn tin 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 trò chuyện 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 Chat API (Event) thay vì Các đố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ề tài nguyên Message thay vì một thao tác.

Để 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 phần 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 một ứ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:

Lượt tương tác của người dùng	`eventType`	Phản hồi thông thường của 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 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.
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 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.
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á webhook) và xoá 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 trên 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 sẽ trả lời lệnh Giới thiệu bằng một tin nhắn giải thích những việc mà ứng dụng Chat có thể làm.

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

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

Nếu ứng dụng Chat không phải là một 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) 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 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 các sự kiện tương tác

Trong bảng điều khiển Google Cloud, 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
Trong phần Tính năng tương tác, hãy xoá Tạo ứng dụng Chat này dưới dạng một tiện ích bổ sung của Google Workspace và đị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, Xem trước đường liên kết và Chế độ hiển thị.
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à một 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`.'
  };
}

Nhận và trả lời hoạt động tương tác của người dùng Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

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

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

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

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

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

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

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

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

Node.js

Python

Java

Apps Script

Cập nhật tin nhắn

Trả lời không đồng bộ bằng Google Chat API

Node.js

Python

Java

Apps Script

Chủ đề có liên quan

Ứng dụng nhắn tin 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 loại sự kiện tương tác

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

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

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

Node.js

Python

Java

Apps Script

Nhận và trả lời hoạt động tương tác của người dùng