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

Bản xem trước dành cho nhà phát triển: Có sẵn như một phần của Chương trình xem trước dành cho nhà phát triển Google Workspace, cho phép truy cập sớm vào một số tính năng nhất định.

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 ứ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 ứng dụng Chat. Chỉ ứng dụng Chat mới có thể xem nội dung của lệnh. Ví dụ: nếu người dùng gửi tin nhắn có lệnh 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 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 trong ứ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 hoặc lệnh nhanh. Để khám phá và sử dụng từng loại lệnh, người dùng làm như sau:

1. Lệnh dấu gạch chéo: Người dùng gửi lệnh dưới dạng tin nhắn bằng cách nhập dấu gạch chéo (/) rồi nhập văn bản được xác định trước, chẳng hạn như /about. Ứng dụng trò chuyện cũng có thể yêu cầu văn bản đối số cho lệnh gạch chéo. Ví dụ: lệnh gạch chéo /search có thể yêu cầu văn bản đối số được dùng cho cụm từ tìm kiếm.
2. Lệnh nhanh: Người dùng sử dụng lệnh bằng cách mở trình đơn từ khu vực trả lời của tin nhắn Chat. Để sử dụng một lệnh, họ nhấp vào biểu tượng Thêm rồi chọn một lệnh trong trình đơn.

Các hình ảnh sau đây cho thấy cách người dùng khám phá trình đơn gồm các lệnh dấu gạch chéo và lệnh nhanh:

• 

  Hình 1. Người dùng khám phá và sử dụng các lệnh dấu gạch chéo bằng cách nhập dấu gạch chéo / vào phần trả lời, theo sau là tên của lệnh.

• 
  Hình 2. Người dùng khám phá và sử dụng các lệnh nhanh trong trình đơn ở khu vực trả lời của tin nhắn trong Chat.

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

HTTP Apps Script

• Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google Chat.
• Tạo dự án trên Google Cloud.
• Định cấu hình màn hình xin phép bằng OAuth.
• Bật các API Google Workspace sau:
  • Google Chat API
  • API tiện ích bổ sung của Google Workspace
    Bạn không thể sử dụng API tiện ích bổ sung của Google Workspace để tạo và quản lý các lượt triển khai ứng dụng Chat. Để biết thông tin chi tiết, hãy xem phần Giới hạn và các vấn đề đã biết.
• Một điểm cuối HTTP lưu trữ cấu trúc dịch vụ cho ứng dụng Chat.

• Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google Chat.
• Tạo dự án trên Google Cloud.
• Định cấu hình màn hình xin phép bằng OAuth.
• Bật API Google Chat.
• Tạo một dự án Apps Script độc lập và bật Dịch vụ trò chuyện nâng cao.
• Định cấu hình tính năng Chat trong tệp kê khai bằng cách thêm đối tượng addons.chat và mọi phạm vi bắt buộc (oauthScopes) hoặc tiền tố URL HTTPS (urlFetchWhitelist).

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:

1. Tạo tên và nội dung mô tả cho lệnh.
2. Định cấu hình lệnh trong Google Cloud Console.

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

Tên của lệnh là nội dung mà người dùng nhập hoặc chọn để gọi ứng dụng Chat. Một 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:

Hình 3: Tên và nội dung mô tả cho 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 lệnh:

• Sử dụng các từ hoặc cụm từ ngắn gọn, 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.
• Cân nhắc sử dụng tên riêng biệt hoặc 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 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 giữ cho nội dung mô tả ngắn gọn và rõ ràng để người dùng biết những gì sẽ xảy ra khi sử dụng lệnh.
• Thông báo cho người dùng biết nếu có yêu cầu định dạng nào đối với lệnh. Ví dụ: nếu bạn tạo một lệnh 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 như Remind me to do [something] at [time].
• Cho người dùng biết liệu ứng dụng Chat có trả lời tất cả mọi người trong không gian hay chỉ trả lời riêng 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 Google Cloud Console

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

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

1. Trong Google Cloud Console, hãy nhấp vào biểu tượng Trình đơn > API và Dịch vụ > API và Dịch vụ đã bật > Google Chat API

   Chuyển đến trang API Google Chat

2. Nhấp vào Cấu hình.

3. Trong phần Cài đặt nâng cao, hãy chuyển đến Trình kích hoạt và kiểm tra để đảm bảo trường Lệnh ứng dụng chứa một trình kích hoạt, chẳng hạn như điểm cuối HTTP hoặc hàm Apps Script. Bạn phải sử dụng điều kiện kích hoạt này trong phần sau để phản hồi lệnh.

4. Trong phần Lệnh, hãy nhấp vào Thêm lệnh.

5. Nhập thông tin sau đây về lệnh:

   1. Mã lệnh: một số từ 1 đến 1000 mà ứng dụng Chat của bạn sử dụng để nhận dạng lệnh và trả về phản hồi.
   2. Loại lệnh: chọn Lệnh nhanh hoặc Lệnh gạch chéo.
   3. Nếu bạn đang định cấu hình lệnh gạch chéo, hãy nhập một giá trị cho trường Tên lệnh gạch chéo để chỉ định nội dung người dùng nhập để gọi lệnh. 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.
   4. Tên: tên thân thiện với người dùng của lệnh. Tên có thể chứa tối đa 50 ký tự và có thể bao gồm cả ký tự đặc biệt.
   5. Mô tả: văn bản mô tả cách sử dụng và định dạng lệnh. Nội dung mô tả có thể chứa tối đa 50 ký tự.

6. Không bắt buộc: Nếu bạn muốn ứng dụng Chat phản hồi lệnh bằng hộp thoại, hãy chọn hộp đánh dấu Mở hộp thoại.

7. 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 lệnh

Khi người dùng sử dụng một lệnh, ứng dụng Chat sẽ nhận được một đối tượng sự kiện. Trọng tải sự kiện chứa đối tượng appCommandPayload có thông tin chi tiết về lệnh đã được gọi (bao gồm mã lệnh và loại lệnh) để bạn có thể trả về phản hồi thích hợp. Đối tượng sự kiện được gửi đến điểm cuối HTTP hoặc hàm Apps Script mà bạn đã chỉ định khi định cấu hình trình kích hoạt Lệnh trong ứng dụng.

Ứng dụng Chat phản hồi riêng tư lệnh gạch chéo /help để giải thích cách yêu cầu hỗ trợ.

Mã sau đây cho thấy ví dụ về một ứng dụng Chat trả lời lệnh gạch chéo /about bằng tin nhắn văn bản. Để phản hồi các lệnh dấu gạch chéo, ứng dụng Chat sẽ xử lý các đối tượng sự kiện từ trình kích hoạt Lệnh ứng dụng. Khi tải trọng của một đối tượng sự kiện chứa mã lệnh dấu gạch chéo, ứng dụng Chat sẽ trả về thao tác DataActions bằng đối tượng createMessageAction:

Node.js Apps Script

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (appCommandMetadata.appCommandId) {
      case ABOUT_COMMAND_ID:
          return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
              text: 'The Avatar app replies to Google Chat messages.'
          }}}}};
  }
}

Để sử dụng mã mẫu này, hãy thay thế ABOUT_COMMAND_ID bằng mã lệnh mà bạn đã chỉ định khi định cấu hình lệnh trong Chat API.

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 phần Sử dụng ứng dụng trong Google Chat trong tài liệu Trợ giúp của Google Chat.

Chủ đề có liên quan

• Xem các mẫu ứng dụng Chat sử dụng lệnh
• Gửi tin nhắn
• Mở hộp thoại tương tác