Halaman ini diterjemahkan oleh Cloud Translation API.

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

Anda dapat mem-build perintah aplikasi Chat sebagai perintah garis miring atau perintah cepat. Untuk menemukan dan menggunakan setiap jenis perintah, pengguna melakukan hal berikut:

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

Gambar berikut menunjukkan cara pengguna menemukan menu perintah garis miring dan perintah cepat:

Gambar 1. Pengguna menemukan dan menggunakan perintah garis miring dengan mengetik garis miring / di area balasan, diikuti dengan nama perintah.
Gambar 2. Pengguna menemukan dan menggunakan perintah cepat dari menu di area balasan pesan Chat.

Prasyarat

HTTP Apps Script

Akun Google Workspace Business atau Enterprise dengan akses ke Google Chat.
Buat project Google Cloud.
Konfigurasikan layar izin OAuth.
Aktifkan Google Workspace API berikut:
- Google Chat API
- API add-on Google Workspace
  Anda tidak dapat menggunakan API add-on Google Workspace untuk membuat dan mengelola deployment aplikasi Chat. Untuk mengetahui detailnya, lihat Batasan dan masalah umum.
Endpoint HTTP yang menghosting arsitektur layanan untuk aplikasi Chat Anda.

Akun Google Workspace Business atau Enterprise dengan akses ke Google Chat.
Buat project Google Cloud.
Konfigurasikan layar izin OAuth.
Aktifkan Google Chat API.
Buat project Apps Script mandiri, dan aktifkan Layanan Chat Lanjutan.
Konfigurasi Chat dalam manifes, dengan menambahkan objek addons.chat dan cakupan yang diperlukan (oauthScopes) atau awalan URL HTTPS (urlFetchWhitelist).

Menyiapkan perintah

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

Buat nama dan deskripsi untuk perintah.
Konfigurasikan perintah di konsol Google Cloud.

Beri nama dan deskripsikan perintah

Nama perintah adalah yang diketik atau dipilih pengguna 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 3**: Nama dan deskripsi untuk perintah garis miring.

Saat memilih nama dan deskripsi untuk perintah, 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 sehingga pengguna tahu apa yang akan terjadi saat mereka menggunakan perintah.
Beri 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 harus menentukan informasi tentang perintah tersebut dalam konfigurasi aplikasi Chat untuk Google Chat API.

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

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

Buka halaman Google Chat API
Klik Konfigurasi.
Di bagian Setelan lanjutan, buka Pemicu dan pastikan kolom Perintah aplikasi berisi pemicu, seperti endpoint HTTP atau fungsi Apps Script. Anda harus menggunakan pemicu ini di bagian berikut untuk merespons perintah.
Di bagian Commands, klik Add a command.
Masukkan informasi berikut tentang perintah:
1. ID Perintah: angka dari 1 hingga 1.000 yang digunakan aplikasi Chat Anda untuk mengenali perintah dan menampilkan respons.
2. Jenis perintah: pilih Perintah cepat atau Perintah garis miring.
3. Jika Anda mengonfigurasi perintah garis miring, masukkan nilai untuk kolom Nama perintah garis miring guna menentukan apa yang diketik pengguna untuk memanggil perintah. Harus diawali dengan garis miring, hanya berisi teks, dan dapat berisi maksimal 50 karakter. Misalnya, /remindMe.
4. Nama: nama yang mudah digunakan untuk perintah. Nama dapat berisi maksimal 50 karakter dan dapat menyertakan karakter khusus.
5. Deskripsi: teks yang menjelaskan cara menggunakan dan memformat perintah. Deskripsi dapat berisi hingga 50 karakter.
Opsional: Jika Anda ingin aplikasi Chat merespons perintah dengan dialog, centang kotak Open a dialog.
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.

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

Untuk menggunakan contoh kode ini, ganti ABOUT_COMMAND_ID dengan ID perintah yang Anda tentukan saat 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.

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