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 mewajibkan 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. 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:

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:

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 Commands, klik Add a command.

4. Masukkan ID perintah, nama, deskripsi, dan jenis perintah untuk perintah:

   • ID Perintah: angka dari 1 hingga 1.000 yang digunakan aplikasi Chat Anda untuk mengenali perintah dan menampilkan respons.
   • Name: nama tampilan untuk perintah. Nama dapat berisi maksimal 50 karakter dan dapat menyertakan karakter khusus.
   • Deskripsi: teks yang menjelaskan fungsi perintah. Deskripsi dapat berisi hingga 50 karakter dan dapat menyertakan karakter khusus.
   • Jenis perintah: pilih Perintah cepat atau Perintah garis miring.
   • 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.

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

6. Klik Simpan.

Perintah kini dikonfigurasi untuk aplikasi Chat.

Merespons perintah

Saat pengguna menggunakan perintah, aplikasi Chat Anda akan menerima peristiwa interaksi. Payload peristiwa berisi metadata dengan detail tentang perintah yang dipanggil (termasuk ID perintah dan jenis perintah), sehingga Anda dapat menampilkan respons yang sesuai.

Untuk merespons setiap jenis perintah, Anda harus menangani berbagai jenis peristiwa dan objek metadata dalam payload peristiwa:

Untuk mempelajari cara merespons perintah dengan pesan, lihat bagian berikut.

Merespons perintah garis miring

Kode berikut menunjukkan contoh aplikasi Chat yang membalas perintah garis miring /about. Aplikasi Chat menangani peristiwa interaksi MESSAGE, mendeteksi apakah peristiwa interaksi berisi ID perintah yang cocok, dan menampilkan pesan pribadi:

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Ganti ABOUT_COMMAND_ID dengan ID perintah yang Anda tentukan saat mengonfigurasi perintah di konsol Google Cloud.

Merespons perintah cepat

Kode berikut menunjukkan contoh aplikasi Chat yang membalas perintah cepat Bantuan. Aplikasi Chat menangani peristiwa interaksi APP_COMMAND, mendeteksi apakah peristiwa interaksi berisi ID perintah yang cocok, dan menampilkan pesan pribadi:

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Ganti HELP_COMMAND_ID dengan ID perintah yang Anda tentukan saat mengonfigurasi perintah di konsol Google Cloud.

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