Trả lời lệnh của ứng dụng Google Chat

Trang này giải thích cách thiết lập và phản hồi các lệnh dưới dạng một ứng dụng Google Chat.

Lệnh giúp người dùng khám phá và sử dụng các tính năng chính của một ứng dụng Chat. Chỉ ứng dụng Chat mới có thể xem nội dung của một lệnh. Ví dụ: nếu người dùng gửi tin nhắn có lệnh dấu gạch chéo, thì chỉ người dùng và ứng dụng Chat mới thấy được tin nhắn đó.

Để quyết định xem bạn có nên tạo các lệnh hay không và để hiểu cách thiết kế các lượt tương tác của người dùng, hãy xem phần Xác định tất cả hành trình của người dùng.

Các loại lệnh của ứng dụng Chat

Bạn có thể tạo lệnh cho ứng dụng Chat dưới dạng lệnh dấu gạch chéo, lệnh nhanh hoặc thao tác trên tin nhắn. Để sử dụng từng loại lệnh, người dùng có thể làm như sau:

Lệnh dấu gạch chéo: Người dùng có thể chọn một lệnh dấu gạch chéo trong trình đơn hoặc nhập dấu gạch chéo (/) rồi nhập một văn bản được xác định trước, chẳng hạn như /about. Các ứng dụng trò chuyện thường yêu cầu văn bản đối số cho lệnh dấu gạch chéo.

Tạo lệnh dấu gạch chéo nếu ứng dụng Chat của bạn yêu cầu người dùng nhập thêm thông tin. Ví dụ: bạn có thể tạo một lệnh dấu gạch chéo có tên là /search. Lệnh này sẽ chạy sau khi người dùng nhập một cụm từ để tìm kiếm, chẳng hạn như /search receipts.
Lệnh nhanh: Người dùng sử dụng lệnh bằng cách mở trình đơn trong phần trả lời của một tin nhắn trên Chat. Để sử dụng một lệnh, họ nhấp vào Thêm rồi chọn một lệnh trong trình đơn.

Tạo một lệnh nhanh nếu ứng dụng Chat của bạn có thể phản hồi ngay cho người dùng mà không cần chờ thêm thông tin đầu vào. Ví dụ: bạn có thể tạo một lệnh nhanh có tên là Hình ảnh ngẫu nhiên và lệnh này sẽ phản hồi ngay lập tức bằng một hình ảnh.
Thao tác với tin nhắn: ( Bản dùng trước cho nhà phát triển) Người dùng sử dụng thao tác với tin nhắn bằng cách di chuột qua một tin nhắn và nhấp vào trình đơn có biểu tượng ba dấu chấm. Để sử dụng một lệnh, họ mở trình đơn có biểu tượng ba dấu chấm rồi chọn một lệnh trong trình đơn đó.

Tạo một thao tác với tin nhắn nếu ứng dụng Chat của bạn có thể thực hiện các thao tác dựa trên ngữ cảnh của một tin nhắn.

Những hình ảnh sau đây cho thấy cách người dùng khám phá trình đơn cho lệnh dấu gạch chéo, lệnh nhanh và thao tác với tin nhắn:

Người dùng khám phá một trình đơn gồm các lệnh dấu gạch chéo và lệnh nhanh.

Người dùng thấy một trình đơn theo bối cảnh của tin nhắn có chứa một thao tác đối với tin nhắn. — Người dùng thấy một trình đơn theo bối cảnh của tin nhắn có chứa thao tác "Nhắc tôi".

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

Node.js

Một ứng dụng Google Chat nhận và phản hồi sự kiện tương tác. Để tạo một ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn tất hướng dẫn bắt đầu nhanh này.

Apps Script

Một ứng dụng Google Chat nhận và phản hồi sự kiện tương tác. Để tạo một ứng dụng Chat có tính tương tác trong Apps Script, hãy hoàn thành hướng dẫn nhanh này.

Python

Java

Thiết lập lệnh

Phần này giải thích cách hoàn tất các bước sau để thiết lập lệnh:

Tạo tên và nội dung mô tả cho lệnh.
Định cấu hình lệnh trong bảng điều khiển Cloud.

Đặt tên và mô tả lệnh

Tên của một lệnh là nội dung mà người dùng nhập hoặc chọn để gọi ứng dụng Chat. Nội dung mô tả ngắn cũng xuất hiện bên dưới tên để nhắc người dùng thêm về cách sử dụng lệnh:

Tên và nội dung mô tả của lệnh dấu gạch chéo — Tên và nội dung mô tả của một lệnh dấu gạch chéo.

Khi chọn tên và nội dung mô tả cho lệnh, hãy cân nhắc những đề xuất sau:

Cách đặt tên cho một lệnh:

Sử dụng các từ hoặc cụm từ ngắn gọn, mang tính mô tả và có thể hành động để người dùng hiểu rõ các lệnh. Ví dụ: thay vì tên Create a reminder, hãy sử dụng Remind me.
Hãy cân nhắc sử dụng một tên riêng biệt hoặc tên phổ biến cho lệnh của bạn. Nếu lệnh của bạn mô tả một tính năng hoặc hoạt động tương tác thông thường, bạn có thể sử dụng một tên phổ biến mà người dùng nhận ra và mong đợi, chẳng hạn như Settings hoặc Feedback. Nếu không, hãy cố gắng sử dụng tên lệnh riêng biệt, vì nếu tên lệnh của bạn giống với tên lệnh của các ứng dụng Chat khác, thì người dùng phải lọc qua các lệnh tương tự để tìm và sử dụng lệnh của bạn.

Cách mô tả một lệnh:

Hãy viết nội dung mô tả ngắn gọn và rõ ràng để người dùng biết được những gì họ có thể mong đợi khi sử dụng lệnh.
Thông báo cho người dùng biết liệu có yêu cầu nào về định dạng đối với lệnh hay không. Ví dụ: nếu bạn tạo một lệnh dấu gạch chéo yêu cầu văn bản đối số, hãy đặt nội dung mô tả thành một nội dung nào đó như Remind me to do [something] at [time].
Cho người dùng biết ứng dụng Chat có trả lời tất cả mọi người trong không gian hay trả lời riêng tư cho người dùng gọi lệnh. Ví dụ: đối với lệnh nhanh About, bạn có thể mô tả lệnh này là Learn about this app (Only visible to you).

Định cấu hình lệnh trong bảng điều khiển Google Cloud

Để tạo lệnh dấu gạch chéo, lệnh nhanh hoặc thao tác trên tin nhắn, bạn hãy chỉ định thông tin về lệnh hoặc thao tác trong cấu hình ứng dụng Chat cho Google Chat API.

Để định cấu hình một lệnh trong Google Chat API, hãy hoàn tất các bước sau:

Trong bảng điều khiển Cloud, hãy nhấp vào Trình đơn > API và Dịch vụ > API và Dịch vụ đã bật > Google Chat API

Truy cập vào trang API Google Chat
Nhấp vào Cấu hình.
Trong phần Lệnh, hãy nhấp vào Thêm lệnh.
Nhập mã lệnh, nội dung mô tả, loại lệnh và tên cho lệnh:
- Mã lệnh: một số từ 1 đến 1000 mà ứng dụng Chat của bạn dùng để nhận dạng lệnh và trả về phản hồi.
- Nội dung mô tả: văn bản mô tả chức năng của lệnh. Nội dung mô tả có thể chứa tối đa 50 ký tự và có thể bao gồm các ký tự đặc biệt.
- Loại lệnh: chọn Lệnh nhanh, Lệnh dấu gạch chéo hoặc Hành động đối với tin nhắn.
- Chỉ định tên cho lệnh:
  - Tên lệnh nhanh: Tên hiển thị mà người dùng chọn trong trình đơn để gọi lệnh. Có thể chứa tối đa 50 ký tự và bao gồm cả ký tự đặc biệt. Ví dụ: Remind me.
  - Tên lệnh dấu gạch chéo: Văn bản mà người dùng nhập để gọi lệnh trong một tin nhắn. Phải bắt đầu bằng dấu gạch chéo, chỉ chứa văn bản và có thể dài tối đa 50 ký tự. Ví dụ: /remindMe.
  - Tên thao tác với tin nhắn: ( Bản dùng trước cho nhà phát triển) Tên hiển thị mà người dùng chọn trong trình đơn để gọi thao tác với tin nhắn. Có thể chứa tối đa 50 ký tự và bao gồm cả ký tự đặc biệt. Ví dụ: Remind me.
Không bắt buộc: Thông báo đang tải: ( Bản dùng trước cho nhà phát triển) Thông báo dạng thông báo ngắn để hiển thị cho người dùng trong khi hành động của thông báo đang thực thi. Chỉ dùng được cho những thao tác đối với tin nhắn không mở hộp thoại.
Không bắt buộc: Nếu bạn muốn ứng dụng Chat phản hồi lệnh bằng một hộp thoại, hãy chọn hộp đánh dấu Mở hộp thoại.
Nhấp vào Lưu.

Lệnh này hiện đã được định cấu hình cho ứng dụng Chat.

Phản hồi một lệnh

Khi người dùng sử dụng một lệnh, ứng dụng Chat của bạn sẽ nhận được một sự kiện tương tác. Tải trọng sự kiện chứa siêu dữ liệu với thông tin chi tiết về lệnh đã được gọi (bao gồm cả mã nhận dạng lệnh và loại lệnh), để bạn có thể trả về một phản hồi thích hợp.

Tin nhắn riêng tư cho ứng dụng Cymbal Labs Chat. Tin nhắn này cho biết ứng dụng Chat do Cymbal Labs tạo và chia sẻ đường liên kết đến tài liệu cũng như đường liên kết để liên hệ với nhóm hỗ trợ. — Ứng dụng Chat sẽ phản hồi riêng cho lệnh dấu gạch chéo `/help` để giải thích cách nhận được sự hỗ trợ.

Để phản hồi từng loại lệnh, bạn phải xử lý các loại sự kiện và đối tượng siêu dữ liệu khác nhau trong tải trọng sự kiện:

Loại lệnh	Loại sự kiện	Siêu dữ liệu lệnh
Lệnh dấu gạch chéo	`MESSAGE`	`message.slashCommand` hoặc `message.annotation.slashCommand`
Lệnh nhanh	`APP_COMMAND`	`appCommandMetadata`
Thao tác đối với tin nhắn	`APP_COMMAND`	`appCommandMetadata`

Để tìm hiểu cách phản hồi một lệnh bằng tin nhắn, hãy xem các phần sau.

Phản hồi lệnh dấu gạch chéo

Đoạn mã sau đây cho thấy ví dụ về một ứng dụng Chat trả lời lệnh dấu gạch chéo /about. Ứng dụng Chat xử lý các sự kiện tương tác MESSAGE, phát hiện xem sự kiện tương tác có chứa mã lệnh khớp hay không và trả về một tin nhắn riêng tư:

Node.js

node/avatar-app/index.js

Xem trên GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

Xem trên GitHub

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

Xem trên GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java

Xem trên GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Thay thế ABOUT_COMMAND_ID bằng mã lệnh mà bạn đã chỉ định khi định cấu hình lệnh trong bảng điều khiển Cloud.

Trả lời một lệnh nhanh

Đoạn mã sau đây cho thấy ví dụ về một ứng dụng trò chuyện trả lời lệnh nhanh Trợ giúp. Ứng dụng Chat xử lý các sự kiện tương tác APP_COMMAND, phát hiện xem sự kiện tương tác có chứa mã lệnh khớp hay không và trả về một tin nhắn riêng tư:

Node.js

node/avatar-app/index.js

Xem trên GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

Xem trên GitHub

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

Xem trên GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java

Xem trên GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Thay thế HELP_COMMAND_ID bằng mã lệnh mà bạn đã chỉ định khi định cấu hình lệnh trong bảng điều khiển Cloud.

Trả lời một thao tác trên tin nhắn

Đoạn mã sau đây cho thấy ví dụ về một ứng dụng trò chuyện trả lời thao tác tin nhắn Nhắc tôi. Ứng dụng Chat xử lý các sự kiện tương tác APP_COMMAND, phát hiện xem sự kiện tương tác có chứa mã lệnh khớp hay không và trả về một tin nhắn riêng tư:

Node.js

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function handleAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  // Use appCommandType to detect message actions.
  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return res.send({
      text: `Setting a reminder for this message: "${messageText}"`
    });
  }
}

Apps Script

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return { "text": "Setting a reminder for message: " + messageText };
  }
}

Python

def handle_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    metadata = event.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = event.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "text": f'Setting a reminder for message: "{message_text}"'
        }

Java

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject metadata = event.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = event.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
      response.getWriter().write(responseMessage.toString());
    }
  }
}

Thay thế REMIND_ME_COMMAND_ID bằng mã lệnh mà bạn đã chỉ định khi định cấu hình lệnh trong bảng điều khiển Cloud.

Kiểm thử lệnh

Để kiểm thử lệnh và mã, hãy xem phần Kiểm thử các tính năng tương tác cho ứng dụng Google Chat.

Để tìm hiểu cách kiểm thử và sử dụng lệnh trong giao diện người dùng Chat, hãy xem bài viết Dùng các ứng dụng trong Google Chat trong tài liệu trợ giúp của Google Chat.

Trả lời lệnh của ứng dụng Google Chat 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.

Các loại lệnh của ứng dụng Chat

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

Node.js

Apps Script

Python

Java

Thiết lập lệnh

Đặt tên và mô tả lệnh

Cách đặt tên cho một lệnh:

Cách mô tả một lệnh:

Định cấu hình lệnh trong bảng điều khiển Google Cloud

Phản hồi một lệnh

Phản hồi lệnh dấu gạch chéo

Node.js

Apps Script

Python

Java

Trả lời một lệnh nhanh

Node.js

Apps Script

Python

Java

Trả lời một thao tác trên tin nhắn

Node.js

Apps Script

Python

Java

Kiểm thử lệnh

Chủ đề có liên quan

Trả lời lệnh của ứng dụng Google Chat