Merespons perintah aplikasi Google Chat

Halaman ini menjelaskan cara menyiapkan dan merespons perintah sebagai aplikasi Google Chat.

Perintah membantu pengguna menemukan dan menggunakan fitur utama aplikasi Chat. Hanya aplikasi Chat yang dapat melihat konten perintah. Misalnya, jika pengguna mengirim pesan dengan perintah garis miring, pesan tersebut hanya dapat dilihat oleh pengguna dan aplikasi Chat.

Untuk memutuskan apakah Anda harus membuat perintah, dan untuk memahami cara mendesain interaksi pengguna, lihat Menentukan semua perjalanan pengguna.

Jenis perintah aplikasi Chat

1. Perintah garis miring: Pengguna mengirim perintah sebagai pesan dengan mengetik garis miring (/) lalu teks yang telah ditentukan, seperti /about. Aplikasi chat juga dapat memerlukan teks argumen untuk perintah garis miring. Misalnya, perintah garis miring /search dapat memerlukan teks argumen yang digunakan untuk kueri penelusuran.
2. Perintah cepat: Pengguna menggunakan perintah dengan membuka menu dari area balasan pesan Chat. Untuk menggunakan perintah, mereka mengklik Tambahkan dan memilih perintah dari menu.

Prasyarat

Menyiapkan perintah

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

1. Buat nama dan deskripsi untuk perintah.
2. Konfigurasi perintah di konsol Google Cloud.

Beri nama dan deskripsikan perintah

Nama perintah adalah apa yang diketik atau dipilih pengguna untuk memanggil aplikasi Chat. Deskripsi singkat juga muncul di bawah nama, untuk mendorong pengguna lebih lanjut tentang cara menggunakan perintah:

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

Untuk memberi nama perintah:

• Gunakan kata atau frasa yang singkat, deskriptif, dan dapat ditindaklanjuti untuk membuat perintah jelas bagi pengguna. Misalnya, gunakan Remind me, bukan nama Create a reminder.
• 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:

• Buat deskripsi singkat dan jelas agar pengguna tahu apa yang akan terjadi saat mereka menggunakan perintah.
• Memberi tahu pengguna jika ada persyaratan pemformatan untuk perintah. Misalnya, jika Anda membuat perintah garis miring 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 cepat About, Anda dapat mendeskripsikannya sebagai Learn about this app (Only visible to you).

Mengonfigurasi perintah di konsol Google Cloud

Untuk membuat perintah garis miring atau cepat, Anda menentukan informasi tentang perintah di konfigurasi aplikasi Chat untuk Google Chat API.

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

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

   Buka halaman Google Chat API

2. Klik Konfigurasi.

3. Di bagian Connection settings, buka Triggers dan tentukan detail endpoint Anda. Anda harus menggunakan pemicu ini di bagian berikut untuk merespons perintah.

   1. URL endpoint HTTP: Anda dapat menentukan satu URL endpoint HTTP umum di sini. Atau, untuk menggunakan endpoint HTTP yang berbeda untuk pemicu yang berbeda, tentukan endpoint langsung di kolom Perintah aplikasi.
   2. Apps Script: Masukkan ID Deployment Apps Script. Secara default, fungsi onAppCommand akan dipanggil. Untuk menggunakan fungsi Apps Script yang berbeda, tentukan nama fungsi kustom di kolom Perintah aplikasi.

4. Di bagian Commands, klik Add a command.

5. Masukkan informasi berikut tentang perintah:

   1. ID Perintah: angka dari 1 hingga 1000 yang digunakan aplikasi Chat Anda untuk mengenali perintah dan menampilkan respons.
   2. Deskripsi: teks yang menjelaskan cara menggunakan dan memformat perintah. Deskripsi dapat berisi hingga 50 karakter.
   3. Jenis perintah: pilih Perintah cepat atau Perintah garis miring.
   4. Tentukan nama untuk perintah cepat atau perintah garis miring:
      • Nama perintah cepat: Nama tampilan yang dipilih pengguna dari menu untuk memanggil perintah. Dapat berisi hingga 50 karakter dan menyertakan karakter khusus. Misalnya, Remind me.
      • Nama perintah garis miring: Teks yang diketik pengguna untuk memanggil perintah dalam pesan. Harus diawali dengan garis miring, hanya berisi teks, dan dapat berisi hingga 50 karakter. Misalnya, /remindMe.

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

7. Klik Simpan.

Perintah kini dikonfigurasi untuk aplikasi Chat.

Merespons perintah

Saat pengguna menggunakan perintah, aplikasi Chat Anda akan menerima objek peristiwa. Payload peristiwa berisi objek appCommandPayload dengan detail tentang perintah yang dipanggil (termasuk ID perintah dan jenis perintah), sehingga Anda dapat menampilkan respons yang sesuai. Objek peristiwa dikirim ke endpoint HTTP atau fungsi Apps Script yang Anda tentukan saat mengonfigurasi pemicu perintah Aplikasi.

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 Perintah aplikasi. Saat payload objek peristiwa berisi ID perintah garis miring, aplikasi Chat akan menampilkan tindakan DataActions dengan objek 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 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.'
          }}}}};
  }
}

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

Menguji perintah

Untuk menguji perintah dan kode, lihat Menguji fitur interaktif untuk aplikasi Google Chat.

Untuk mempelajari cara menguji dan menggunakan perintah di UI Chat, lihat Menggunakan aplikasi di Google Chat dalam dokumentasi Bantuan Google Chat.

Topik terkait

• Melihat contoh aplikasi Chat yang menggunakan perintah
• Mengirim pesan
• Membuka dialog interaktif