Merespons perintah garis miring di Google Chat

Halaman ini menjelaskan cara mengonfigurasi aplikasi Google Chat untuk merespons perintah garis miring.

Di Google Chat, add-on akan muncul kepada pengguna sebagai aplikasi Google Chat. Untuk mempelajari lebih lanjut, lihat Ringkasan memperluas Google Chat.

Perintah garis miring adalah cara umum yang digunakan pengguna untuk memanggil dan berinteraksi dengan aplikasi Chat. Perintah garis miring juga membantu pengguna menemukan dan menggunakan fitur utama aplikasi Chat. Untuk memutuskan apakah Anda harus menyiapkan perintah garis miring, dan untuk memahami cara mendesain interaksi pengguna, lihat Menentukan semua perjalanan pengguna dalam dokumentasi Chat API.

Cara pengguna menggunakan perintah garis miring

Untuk menggunakan perintah garis miring, pengguna mengetik garis miring (/), lalu perintah teks singkat, seperti /about untuk mendapatkan informasi tentang aplikasi Chat. Pengguna dapat menemukan perintah garis miring yang tersedia dengan mengetik garis miring ke dalam Google Chat, yang akan menampilkan jendela yang mencantumkan perintah yang tersedia untuk aplikasi Chat:

Jendela perintah garis miring
Gambar 1: Jendela yang muncul saat pengguna mengetik garis miring di Google Chat.

Saat pengguna mengirim pesan yang berisi perintah garis miring, pesan tersebut hanya terlihat oleh pengguna dan aplikasi Chat. Jika Anda telah mengonfigurasi aplikasi Chat untuk ditambahkan ke ruang dengan beberapa orang, sebaiknya pertimbangkan untuk merespons perintah garis miring secara pribadi, agar interaksi tetap bersifat pribadi antara pengguna dan aplikasi Chat.

Misalnya, untuk mempelajari aplikasi Chat yang mereka temukan di ruang, pengguna dapat menggunakan perintah seperti /about atau /help. Untuk menghindari notifikasi kepada semua orang di ruang, aplikasi Chat dapat merespons secara pribadi dengan informasi tentang cara menggunakan aplikasi Chat dan mendapatkan dukungan.

Prasyarat

Node.js

Add-on Google Workspace yang memperluas Google Chat. Untuk membuatnya, selesaikan panduan memulai HTTP.

Apps Script

Add-on Google Workspace yang memperluas Google Chat. Untuk membuatnya, selesaikan panduan memulai Apps Script.

Menyiapkan perintah garis miring

Bagian ini menjelaskan cara menyelesaikan langkah-langkah berikut untuk menyiapkan perintah garis miring:

  1. Buat nama untuk perintah slash Anda.
  2. Konfigurasikan perintah garis miring di Google Chat API.

Beri nama perintah garis miring Anda

Nama perintah garis miring adalah yang diketik pengguna dalam pesan Chat untuk memanggil aplikasi Chat. Deskripsi singkat juga muncul di bawah nama, untuk meminta pengguna lebih lanjut tentang cara menggunakan perintah:

Nama dan deskripsi perintah garis miring
Gambar 2: Nama dan deskripsi untuk perintah garis miring.

Saat memilih nama dan deskripsi untuk perintah garis miring, pertimbangkan rekomendasi berikut:

  • Untuk memberi nama perintah garis miring:

    • Gunakan kata atau frasa yang singkat, deskriptif, dan dapat ditindaklanjuti untuk membuat perintah jelas dan sederhana bagi pengguna. Misalnya, gunakan /remindMe, bukan /createAReminder.
    • Jika perintah Anda berisi lebih dari satu kata, bantu pengguna membaca perintah dengan menggunakan huruf kecil untuk kata pertama, lalu menggunakan huruf besar pada huruf pertama kata tambahan. Misalnya, gunakan /updateContact, bukan /updatecontact.
    • Pertimbangkan untuk menggunakan nama unik atau umum untuk perintah Anda. Jika perintah Anda menjelaskan interaksi atau fitur umum, Anda dapat menggunakan nama umum yang dikenali dan diharapkan pengguna, seperti /settings atau /feedback. Jika tidak, coba gunakan nama perintah yang unik, karena jika nama perintah Anda sama dengan aplikasi Chat lainnya, pengguna harus memfilter perintah serupa untuk menemukan dan menggunakan perintah Anda.

  • Untuk mendeskripsikan perintah garis miring:

    • Buat deskripsi singkat dan jelas sehingga pengguna tahu apa yang akan terjadi saat mereka memanggil perintah.
    • Beri tahu pengguna jika ada persyaratan pemformatan untuk perintah. Misalnya, jika Anda membuat perintah /remindMe yang memerlukan teks argumen, tetapkan deskripsi ke sesuatu seperti Remind me to do [something] at [time].
    • Beri tahu pengguna apakah aplikasi Chat membalas semua orang di ruang, atau secara pribadi kepada pengguna yang memanggil perintah. Misalnya, untuk perintah garis miring /about, Anda dapat mendeskripsikannya sebagai Learn about this app (Only visible to you).

Mengonfigurasi perintah garis miring di Google Chat API

Untuk membuat perintah garis miring, Anda perlu menentukan informasi tentang perintah tersebut dalam konfigurasi aplikasi Chat untuk Google Chat API.

Untuk mengonfigurasi perintah garis miring di Google Chat API, selesaikan langkah-langkah berikut:

  1. Di konsol Google Cloud, klik Menu > APIs & Services > Enabled APIs & Services > Google Chat API

    Buka halaman Google Chat API

  2. Klik Konfigurasi.

  3. Di bagian Setelan lanjutan, buka Pemicu dan pastikan kolom MESSAGE berisi pemicu, seperti endpoint HTTP atau fungsi Apps Script. Anda harus menggunakan pemicu ini untuk di bagian berikut guna merespons perintah garis miring.

  4. Di bagian Slash commands, klik Add a slash command.

  5. Masukkan nama, ID perintah, dan deskripsi untuk perintah:

    1. Nama: nama tampilan untuk perintah, dan yang diketik pengguna untuk memanggil aplikasi Anda. Harus diawali dengan garis miring, hanya berisi teks, dan dapat berjumlah maksimal 50 karakter.
    2. Deskripsi: teks yang menjelaskan cara menggunakan dan memformat perintah. Deskripsi dapat berisi hingga 50 karakter.
    3. ID Perintah: angka dari 1 hingga 1.000 yang digunakan aplikasi Chat Anda untuk mengenali perintah garis miring dan menampilkan respons.

  6. Opsional: Jika Anda ingin aplikasi Chat merespons perintah dengan dialog, centang kotak Buka dialog.

  7. Klik Simpan.

Perintah garis miring kini dikonfigurasi untuk aplikasi Chat.

Merespons perintah garis miring

Saat pengguna membuat pesan Chat, aplikasi Chat Anda akan menerima objek peristiwa yang berisi informasi tentang pesan tersebut. Objek peristiwa berisi payload dengan detail tentang perintah yang digunakan dalam pesan (termasuk ID perintah), sehingga Anda dapat menampilkan respons yang sesuai.

Untuk merespons perintah garis miring, Anda harus menerapkan pemicu Pesan sehingga aplikasi Chat Anda dapat menangani objek peristiwa yang berisi metadata perintah garis miring.

Pesan pribadi untuk aplikasi Chat Cymbal Labs. Pesan tersebut menyatakan bahwa aplikasi Chat dibuat oleh Cymbal Labs dan membagikan link ke dokumentasi serta link untuk menghubungi tim dukungan.
Aplikasi Chat merespons secara pribadi perintah garis miring /help untuk menjelaskan cara mendapatkan dukungan.

Kode berikut menunjukkan contoh aplikasi Chat yang membalas perintah garis miring /about dengan pesan teks. Untuk merespons perintah garis miring, aplikasi Chat menangani objek peristiwa dari pemicu Pesan. Jika payload objek peristiwa berisi ID perintah garis miring, aplikasi Chat akan menampilkan tindakan DataActions dengan objek createMessageAction:

Node.js 

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

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;

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

Untuk menggunakan contoh kode ini, ganti ABOUT_COMMAND_ID dengan ID perintah yang Anda tentukan saat mengonfigurasi perintah garis miring di Chat API.