Menerima dan merespons interaksi pengguna

Halaman ini menjelaskan cara aplikasi Google Chat Anda dapat menerima dan merespons interaksi pengguna di Google Chat.

Untuk membuat antarmuka interaktif bagi aplikasi Chat, Anda menggunakan komponen berikut:

• Pemicu: Cara pengguna Google Chat dapat memanggil aplikasi Chat, seperti menambahkannya ke ruang atau mengirim pesan ke aplikasi tersebut.
• Objek peristiwa: Data yang diterima aplikasi Chat dari pemicu atau interaksi UI.
• Tindakan: Cara aplikasi Chat dapat merespons interaksi, seperti mengirim pesan atau menampilkan antarmuka pengguna berbasis kartu.

Aplikasi chat dapat membuat dan menampilkan antarmuka dengan cara berikut:

• Pesan yang dapat berisi teks, kartu statis atau interaktif, dan tombol aksesori.
• Halaman beranda (Beranda Aplikasi) yang muncul di tab Beranda pada pesan langsung 1:1 dengan aplikasi Chat.
• Dialog, yaitu kartu yang terbuka di jendela baru dan biasanya meminta pengguna untuk mengirimkan informasi.
• Pratinjau link, yaitu kartu yang menampilkan pratinjau informasi tentang layanan eksternal.

Prasyarat

• Akun Google Workspace Business atau Enterprise dengan akses ke Google Chat.
• Buat project Google Cloud.
• Konfigurasi layar izin OAuth.
• Aktifkan dan konfigurasi Google Chat API.

Cara kerja interaksi pengguna

Saat pengguna berinteraksi dengan aplikasi Chat, Google Chat akan memanggil pemicu yang dikonfigurasi dan mengirim objek peristiwa ke endpoint atau fungsi aplikasi Chat Anda. Aplikasi Chat Anda memproses objek peristiwa dan dapat menampilkan tindakan secara serentak dalam waktu 30 detik atau merespons secara asinkron menggunakan Chat API.

Diagram berikut menunjukkan cara aplikasi Google Chat memproses dan merespons interaksi pengguna:

Pemicu

Pemicu adalah cara khusus pengguna memanggil aplikasi Chat menggunakan UI Chat, seperti menggunakan @sebutan atau perintah aplikasi.

Tabel berikut menunjukkan pemicu Chat, deskripsi, dan cara aplikasi Chat biasanya merespons:

Anda mengonfigurasi endpoint atau fungsi callback untuk pemicu ini di Konsol Google Cloud pada halaman Configuration Chat API. Untuk mengetahui petunjuk langkah demi langkah, lihat Mengonfigurasi Google Chat API.

Mengonfigurasi perintah pemicu

Perintah awal membantu pengguna menemukan fungsi aplikasi Chat Anda saat mereka membuka pesan langsung personal yang kosong dengan aplikasi Anda. Anda dapat mengonfigurasi hingga tiga perintah awal.

Untuk menambahkan dan mengonfigurasi perintah pemicu:

1. Di konsol Google Cloud, buka halaman Configuration Chat API:

   Buka halaman Konfigurasi Chat API

2. Di bagian Fitur interaktif, cari Perintah awal, lalu klik Tambahkan perintah.

3. Di kolom Peringkat (1-3), masukkan angka dari 1 hingga 3 untuk menentukan urutan tampilan.

4. Di bagian Pemilihan jenis, pilih cara kerja perintah:

   • Perintah teks: Mengisi kolom tulis dengan teks yang telah ditentukan sebelumnya saat pengguna mengklik chip perintah.
   • Command prompt: Menjalankan perintah garis miring atau perintah cepat yang terdaftar saat diklik. Perintah yang memerlukan argumen tambahan tidak dapat dipilih.

5. Konfigurasi perintah berdasarkan pilihan jenis Anda:

   • Jika Anda memilih Perintah teks:

     1. Di Judul, masukkan judul perintah yang ditampilkan di chip (hingga 30 karakter).
     2. Di Teks perintah, masukkan teks yang diisi di kolom penulisan (hingga 60 karakter).
     3. Opsional: Tambahkan judul dan teks yang dilokalkan untuk pengguna dalam bahasa lain:
     4. Di bagian Perintah yang dilokalkan, klik Tambahkan bahasa.
     5. Di Bahasa, pilih bahasa yang didukung dari menu drop-down.
     6. Di Localized Title, masukkan judul yang dilokalkan (hingga 30 karakter).
     7. Di Localized Prompt text, masukkan teks perintah yang dilokalkan (hingga 60 karakter).
     8. Ulangi untuk menambahkan lebih banyak bahasa sesuai kebutuhan.

   • Jika Anda memilih Command prompt:

     1. Di Perintah garis miring / Perintah cepat, pilih perintah dari menu drop-down.

6. Klik Selesai, lalu klik Simpan di bagian bawah halaman.

Menangani percobaan ulang panggilan HTTP ke layanan Anda

Jika permintaan HTTPS ke layanan Anda gagal (seperti waktu tunggu habis, kegagalan jaringan sementara, atau kode status HTTPS non-2xx), Google Chat mungkin mencoba lagi pengiriman beberapa kali dalam beberapa menit (tetapi hal ini tidak dijamin). Akibatnya, aplikasi Chat mungkin menerima peristiwa yang sama beberapa kali dalam situasi tertentu. Jika permintaan berhasil diselesaikan, tetapi menampilkan payload respons yang tidak valid, Google Chat tidak akan mencoba lagi permintaan tersebut.

Objek peristiwa

Aplikasi Chat menerima objek peristiwa saat pemicu Chat berjalan, atau saat pengguna Chat berinteraksi dengan UI dari aplikasi Chat (seperti mengklik tombol atau mengirimkan dialog). Objek peristiwa memungkinkan Anda menggunakan data interaksi untuk merespons atau memperbarui UI.

Payload objek peristiwa

Setiap objek peristiwa Chat menyertakan commonEventObject dengan detail host dan platform (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters, dan formInputs) serta objek chat yang berisi konteks khusus Chat:

• Untuk pemicu Beranda Aplikasi (saat pengguna membuka tab Beranda dalam pesan langsung personal dengan aplikasi Chat), objek chat berisi chat.user dan chat.eventTime tanpa kolom gabungan payload. Saat pengguna mengklik tombol di kartu halaman beranda, objek peristiwa akan menyertakan chat.buttonClickedPayload bersama dengan commonEventObject.parameters (dan commonEventObject.formInputs jika kartu berisi input formulir).
• Untuk interaksi ruang dan pesan (Ditambahkan ke ruang, Pesan, Dikeluarkan dari ruang, Perintah aplikasi, atau interaksi tombol dan widget), objek chat mencakup chat.user, chat.space, chat.eventTime, dan payload interaksi yang sesuai:
  • messagePayload: Berisi space, message, dan configCompleteRedirectUri saat pengguna mengirim pesan.
  • addedToSpacePayload: Berisi space, interactionAdd, dan configCompleteRedirectUri saat aplikasi Chat ditambahkan ke ruang.
  • removedFromSpacePayload: Berisi space saat aplikasi Chat dihapus dari ruang.
  • buttonClickedPayload: Berisi space, message, isDialogEvent, dan dialogEventType saat pengguna mengklik tombol pada kartu atau dialog.
  • widgetUpdatedPayload: Berisi space saat pengguna berinteraksi dengan widget, seperti mengetik ke dalam menu multiselect dengan sumber data eksternal.
  • appCommandPayload: Berisi space, message, appCommandMetadata, isDialogEvent, dialogEventType, dan configCompleteRedirectUri saat pengguna memanggil perintah aplikasi.

Untuk mempelajari objek peristiwa add-on dalam Chat dan aplikasi Google Workspace lainnya, lihat Objek peristiwa.

Memberikan respons

Bagian ini menjelaskan cara aplikasi Chat menggunakan tindakan untuk merespons interaksi pengguna secara sinkron.

Untuk merespons dengan tindakan, aplikasi Chat harus merespons dalam waktu 30 detik, dan respons harus berlaku untuk ruang tempat interaksi terjadi. Respons sinkron ini tidak memerlukan autentikasi. Jika aplikasi Chat Anda memerlukan waktu lebih dari 30 detik atau perlu bertindak di luar ruang, siapkan autentikasi dan berikan respons secara asinkron menggunakan Google Chat API.

Untuk merespons interaksi pengguna secara sinkron, aplikasi Chat Anda menangani objek peristiwa masuk dan menampilkan salah satu objek JSON berikut:

• DataActions: Membuat atau memperbarui Pesan chat (CreateMessageAction, UpdateMessageAction) atau melampirkan pratinjau link (UpdateInlinePreviewAction) menggunakan chatDataActionMarkup.
• RenderActions: Membuat, memperbarui, atau menutup halaman beranda atau dialog (pushCard, updateCard, endNavigation: "CLOSE_DIALOG"), atau memberikan saran input dinamis untuk menu multi-pilihan (modifyCard).
• AuthorizationError: Mendorong pengguna dengan kartu otorisasi dasar (basic_authorization_prompt) untuk login atau mengautentikasi ke layanan eksternal.

Tabel berikut menunjukkan cara aplikasi Chat dapat merespons dengan tindakan. Aplikasi Chat dapat menampilkan objek JSON secara langsung atau membuat respons menggunakan AddOnResponseService dan CardService Apps Script.

Balas dengan pesan

Aplikasi chat dapat merespons dengan pesan ke salah satu pemicu atau interaksi berikut:

• Pemicu pesan, seperti saat pengguna @menyebut atau mengirim pesan langsung ke aplikasi Chat.
• Pemicu Ditambahkan ke ruang, seperti saat pengguna menginstal aplikasi Chat dari Google Workspace Marketplace atau menambahkannya ke ruang.
• Pemicu perintah aplikasi, seperti saat pengguna memanggil perintah garis miring atau perintah cepat.
• Klik tombol dari kartu dalam pesan atau dialog. Misalnya, saat pengguna memasukkan informasi dan mengklik kirim.

Aplikasi chat dapat menyertakan salah satu hal berikut dalam pesan:

• Teks yang berisi hyperlink, @sebutan, dan emoji. Lihat Memformat pesan.
• Satu atau beberapa kartu, yang dapat muncul dalam pesan atau terbuka di jendela baru sebagai dialog. Lihat Membangun kartu untuk aplikasi Google Chat.
• Satu atau beberapa widget aksesori, yang merupakan tombol yang muncul setelah teks atau kartu dalam pesan.

Untuk membalas dengan pesan, tampilkan DataActions dengan objek CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Ganti MESSAGE dengan resource Message dari Chat API.

Dalam contoh berikut, aplikasi Chat membuat dan mengirimkan pesan teks aktivasi setiap kali aplikasi ditambahkan ke ruang dengan merespons pemicu Ditambahkan ke ruang dengan DataActions:

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
    }}}}});
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "text": 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
      }}
    }}})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "Hi, Cymbal at your service. I help you manage your calendar " +
                "from Google Chat. Take a look at your schedule today by typing " +
                "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
                "To learn what else I can do, type `/help`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
          'from Google Chat. Take a look at your schedule today by typing ' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
          'To learn what else I can do, type `/help`.'
  }}}}};
}

Contoh kode menampilkan pesan teks berikut:

Memperbarui pesan

Aplikasi chat juga dapat memperbarui pesan yang dikirimnya. Misalnya, aplikasi Chat dapat memperbarui pesan setelah pengguna mengirimkan dialog atau mengklik tombol pada kartu dalam pesan.

Untuk memperbarui pesan aplikasi Chat sebagai respons terhadap interaksi, kembalikan DataActions dengan UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Ganti MESSAGE dengan resource Message dari Chat API.

Aplikasi Chat juga dapat memperbarui pesan yang dikirim oleh pengguna untuk melampirkan kartu pratinjau link menggunakan updateInlinePreviewAction. Untuk mengetahui detailnya, lihat Link pratinjau.

Memberikan respons secara asinkron menggunakan Google Chat API

Daripada menampilkan tindakan secara serentak, aplikasi Chat mungkin perlu memanggil Google Chat API untuk merespons interaksi atau mengirim pesan proaktif. Misalnya, aplikasi Chat harus memanggil Google Chat API untuk melakukan salah satu hal berikut:

• Merespons interaksi setelah 30 detik (seperti setelah menyelesaikan tugas yang berjalan lama).
• Mengirim pesan sesuai jadwal, atau mengirim notifikasi tentang perubahan pada resource eksternal.
• Melakukan tugas di luar ruang tempat interaksi terjadi.
• Melakukan tugas di Chat yang tidak tersedia sebagai tindakan sinkron, seperti mencantumkan ruang atau menambahkan anggota ke ruang.
• Melakukan tugas atas nama pengguna Chat (yang memerlukan autentikasi pengguna).

Saat merespons interaksi setelah 30 detik, untuk menghindari pesan error yang ditampilkan kepada pengguna yang menyatakan bahwa aplikasi Chat Anda tidak merespons, Anda harus mengonfirmasi penerimaan objek peristiwa dalam waktu 30 detik dengan menampilkan respons kosong:

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Untuk mengirim pesan menggunakan Chat API, siapkan autentikasi dan panggil metode spaces.messages.create. Untuk mengetahui langkah-langkahnya, lihat Mengirim pesan. Untuk panduan tentang penggunaan metode Chat API tambahan, lihat Ringkasan Chat API.

Topik terkait

• Mengonfigurasi Google Chat API
• Mengirim pesan
• Menanggapi perintah
• Membuka dialog interaktif
• Membaca input data formulir yang dimasukkan oleh pengguna pada kartu
• Link pratinjau
• Membangun halaman beranda untuk aplikasi Chat
• Memverifikasi permintaan dari Chat
• Menguji fitur interaktif untuk aplikasi Google Chat

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
        'learn what else I can do, type `/help`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
      'learn what else I can do, type `/help`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "Hi, Cymbal at your service. I help you manage your calendar " +
          "from Google Chat. Take a look at your schedule today by typing " +
          "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
          "To learn what else I can do, type `/help`.");
      default:
        return new Message();
    }
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onAddToSpace(event) {
  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn ' +
      'what else I can do, type `/help`.'
  };
}