Phản hồi lệnh gạch chéo trong Google Chat

Trang này giải thích cách định cấu hình ứng dụng Google Chat để phản hồi các lệnh gạch chéo.

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.

Lệnh dấu gạch chéo là một cách phổ biến để người dùng gọi và tương tác với ứng dụng Chat. Lệnh dấu gạch chéo cũng 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. Để quyết định xem bạn có nên thiết lập lệnh dấu gạch chéo hay không và để hiểu cách thiết kế hoạt động 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 trong tài liệu về Chat API.

Cách người dùng sử dụng lệnh có dấu gạch chéo

Để sử dụng lệnh dấu gạch chéo, người dùng nhập dấu gạch chéo (/) rồi nhập một lệnh văn bản ngắn, chẳng hạn như /about để nhận thông tin về ứng dụng Chat. Người dùng có thể khám phá các lệnh dấu gạch chéo hiện có bằng cách nhập dấu gạch chéo vào Google Chat. Thao tác này sẽ hiển thị một cửa sổ liệt kê các lệnh hiện có cho ứng dụng Chat:

Khi người dùng gửi một tin nhắn chứa lệnh dấu gạch chéo, thì tin nhắn đó chỉ hiển thị với người dùng và ứng dụng Chat. Nếu đã định cấu hình ứng dụng Chat để thêm vào không gian có nhiều người, bạn có thể cân nhắc phản hồi lệnh dấu gạch chéo một cách riêng tư để giữ bí mật nội dung tương tác giữa người dùng và ứng dụng Chat.

Ví dụ: để tìm hiểu về một ứng dụng Chat mà họ khám phá được trong một không gian, người dùng có thể sử dụng các lệnh như /about hoặc /help. Để tránh thông báo cho mọi người khác trong không gian, ứng dụng Chat có thể phản hồi riêng tư bằng thông tin về cách sử dụng ứng dụng Chat và cách yêu cầu hỗ trợ.

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

Thiết lập lệnh dấu gạch chéo

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 dấu gạch chéo:

1. Tạo tên cho lệnh gạch chéo.
2. Định cấu hình lệnh gạch chéo trong API Google Chat.

Đặt tên cho lệnh dấu gạch chéo

Tên của lệnh dấu gạch chéo là nội dung mà người dùng nhập vào tin nhắn Chat để 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:

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

• Cách đặt tên cho lệnh dấu gạch chéo:

  • Sử dụng các từ hoặc cụm từ ngắn gọn, mô tả và có thể hành động để giúp người dùng hiểu rõ và đơn giản về các lệnh. Ví dụ: thay vì nói /createAReminder, hãy sử dụng /remindMe.
  • Nếu lệnh của bạn chứa nhiều từ, hãy giúp người dùng đọc lệnh bằng cách viết thường toàn bộ từ đầu tiên, sau đó viết hoa chữ cái đầu tiên của các từ khác. Ví dụ: thay vì /updatecontact, hãy sử dụng /updateContact.
  • Cân nhắc việc sử dụng tên riêng biệt hay tên phổ biến cho lệnh của bạn. Nếu lệnh của bạn mô tả một hoạt động tương tác hoặc tính năng thông thường, bạn có thể sử dụng 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, 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ả lệnh dấu gạch chéo:

  • Hãy giữ cho nội dung mô tả ngắn gọn và rõ ràng để người dùng biết điều gì sẽ xảy ra khi họ gọi 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 /remindMe 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 gạch chéo /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 gạch chéo trong API Google Chat

Để tạo lệnh gạch chéo, bạn cầ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 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 menu > 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 rằng trường MESSAGE (TIN NHẮN) 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 gạch chéo.

4. Trong phần Lệnh dấu gạch chéo, hãy nhấp vào Thêm lệnh dấu gạch chéo.

5. Nhập tên, mã lệnh và nội dung mô tả cho lệnh:

   1. Tên: tên hiển thị của lệnh và nội dung người dùng nhập để gọi ứng dụng của bạ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ự.
   2. 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ự.
   3. 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 gạch chéo và trả về phản hồi.

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 dấu gạch chéo hiện đã được định cấu hình cho ứng dụng Chat.

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

Khi người dùng tạo một tin nhắn Chat, ứng dụng Chat sẽ nhận được một đối tượng sự kiện chứa thông tin về tin nhắn đó. Đối tượng sự kiện chứa một trọng tải với thông tin chi tiết về lệnh được sử dụng trong thông báo (bao gồm cả mã lệnh) để bạn có thể trả về phản hồi thích hợp.

Để phản hồi lệnh gạch chéo, bạn phải triển khai trình kích hoạt Tin nhắn để ứng dụng Chat có thể xử lý mọi đối tượng sự kiện chứa siêu dữ liệu lệnh gạch chéo.

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 một tin nhắn văn bản. Để phản hồi các lệnh 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 Tin nhắn. 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:

// 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 messages 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 chatMessage = req.body.chat.messagePayload.message;

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

    // 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;

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

    // 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 }
                    }]
                }]
            }
        }]
    }}}}};
}

Để 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 gạch chéo trong Chat API.