Merespons perintah aplikasi Google Chat

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

Catatan: Di Google Chat, add-on muncul kepada pengguna sebagai aplikasi Google Chat. Anda juga dapat membuat aplikasi Chat menggunakan peristiwa interaksi Google Chat API. Untuk mempelajari lebih lanjut, lihat Ringkasan cara memperluas 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 Tentukan semua perjalanan pengguna.

Jenis perintah aplikasi Chat

Anda dapat membuat perintah aplikasi Chat sebagai perintah garis miring, perintah cepat, atau tindakan pesan. Untuk menggunakan setiap jenis perintah, pengguna dapat melakukan hal berikut:

1. Perintah garis miring: Pengguna dapat memilih perintah garis miring dari menu atau mengetik garis miring (/) lalu teks yang telah ditentukan sebelumnya, seperti /about. Aplikasi chat biasanya memerlukan teks argumen untuk perintah garis miring.

   Buat perintah garis miring jika aplikasi Chat Anda memerlukan input tambahan dari pengguna. Misalnya, Anda dapat membuat perintah garis miring yang disebut /search yang berjalan setelah pengguna memasukkan frasa untuk menelusuri, seperti /search receipts.

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.

   Buat perintah cepat jika aplikasi Chat Anda dapat langsung merespons pengguna, tanpa menunggu input tambahan. Misalnya, Anda dapat membuat perintah cepat yang disebut Gambar acak yang langsung merespons dengan gambar.

3. Tindakan pesan: (Pratinjau Developer ) Pengguna menggunakan tindakan pesan dengan mengarahkan kursor ke pesan dan mengklik menu tiga titik. Untuk menggunakan perintah, mereka membuka menu tiga titik dan memilih perintah dari menu.

   Buat tindakan pesan jika aplikasi Chat Anda dapat melakukan tindakan berdasarkan konteks pesan.

Gambar berikut menunjukkan cara pengguna menemukan menu untuk perintah garis miring dan cepat, serta tindakan pesan:

Pengguna menemukan menu perintah garis miring dan perintah cepat.

Pengguna menemukan menu konteks pesan yang berisi tindakan pesan "Ingatkan saya".

Prasyarat

HTTP

Add-on Google Workspace yang memperluas Google Chat. Untuk membuatnya, selesaikan mulai cepat HTTP.

Catatan: Contoh kode dalam panduan ini ditulis untuk dijalankan sebagai fungsi Google Cloud Run untuk Node.js.

Apps Script

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

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 lebih memandu pengguna tentang cara menggunakan perintah:

Nama dan deskripsi untuk perintah garis miring.

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

Untuk menamai 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, perintah cepat, atau tindakan pesan, Anda menentukan informasi tentang perintah atau tindakan di 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 > APIs & Services > Enabled APIs & Services > Google Chat API

   Buka halaman Google Chat API

2. Klik Konfigurasi.

3. Di bagian Setelan koneksi, buka Pemicu 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, Perintah garis miring, atau Tindakan pesan.
   4. Tentukan nama untuk perintah:
      • 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.
      • Nama tindakan pesan: (Pratinjau Developer ) Nama tampilan yang dipilih pengguna dari menu untuk memanggil tindakan pesan. Dapat berisi hingga 50 karakter dan menyertakan karakter khusus. Contoh, Remind me.

6. Opsional: Pesan notifikasi pemuatan: (Pratinjau Developer ) Pesan notifikasi toast yang akan ditampilkan kepada pengguna saat tindakan pesan sedang dieksekusi. Hanya tersedia untuk tindakan pesan yang tidak membuka dialog.

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

8. 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 Anda mengonfigurasi pemicu perintah Aplikasi.

Aplikasi Chat merespons perintah garis miring /help secara pribadi 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

node/chat/avatar-app/index.js

Lihat di GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/chat/avatar-app/main.py

Lihat di GitHub

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

Java

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java

Lihat di GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

Apps Script

apps-script/chat/avatar-app/Code.gs

Lihat di GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.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.

Tindakan merespons pesan

Pratinjau Developer: Tersedia sebagai bagian dari Program Pratinjau Developer Google Workspace, yang memberikan akses awal ke fitur tertentu.

Kode berikut menunjukkan contoh aplikasi Chat yang membalas tindakan pesan Ingatkan saya dengan pesan teks. Untuk merespons tindakan pesan, aplikasi Chat menangani objek peristiwa dari pemicu Perintah aplikasi. Saat payload objek peristiwa berisi ID perintah tindakan pesan, aplikasi Chat akan menampilkan tindakan DataActions dengan objek createMessageAction:

Node.js

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return res.json({
      "hostAppDataAction": {
        "chatDataAction": {
          "createMessageAction": {
            "message": {
              "text": `Setting a reminder for message: "${messageText}"`
            }
          }
        }
      }
    });
  }
}

Python

def on_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    payload = event.get('chat', {}).get('appCommandPayload', {})
    metadata = payload.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = payload.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "hostAppDataAction": {
                "chatDataAction": {
                    "createMessageAction": {
                        "message": {
                            "text": f'Setting a reminder for message: "{message_text}"'
                        }
                    }
                }
            }
        }

Java

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void onAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
  JsonObject metadata = payload.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = payload.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);

      JsonObject createMessageAction = new JsonObject();
      createMessageAction.add("message", responseMessage);

      JsonObject chatDataAction = new JsonObject();
      chatDataAction.add("createMessageAction", createMessageAction);

      JsonObject hostAppDataAction = new JsonObject();
      hostAppDataAction.add("chatDataAction", chatDataAction);

      JsonObject finalResponse = new JsonObject();
      finalResponse.add("hostAppDataAction", hostAppDataAction);

      response.getWriter().write(finalResponse.toString());
    }
  }
}

Apps Script

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return CardService.newChatResponseBuilder()
        .setText("Setting a reminder for message: " + messageText)
        .build();
  }
}

Untuk menggunakan contoh kode ini, ganti REMIND_ME_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 di dokumentasi Bantuan Google Chat.

Topik terkait

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