Membangun antarmuka Google Chat

Halaman ini memberikan ringkasan tentang cara membuat antarmuka pengguna (UI) untuk add-on Google Workspace yang memperluas Google Chat.

Untuk membangun antarmuka aplikasi Chat, Anda menggunakan komponen add-on 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 menerima objek peristiwa dari pemicu Ditambahkan ke ruang
Gambar 1: Saat pengguna menambahkan aplikasi Chat ke ruang, pemicu Ditambahkan ke ruang akan diaktifkan dan mengirim objek peristiwa. Untuk merespons dengan pesan, aplikasi Chat menangani objek peristiwa dan menampilkan tindakan yang membuat pesan.

Aplikasi Chat dapat membuat dan menampilkan kartu di antarmuka berikut:

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

Pemicu

Bagian ini menjelaskan pemicu yang digunakan add-on Google Workspace di Chat.

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:

Pemicu Deskripsi Respons umum
Ditambahkan ke ruang

Pengguna menambahkan aplikasi Chat ke ruang, atau administrator Google Workspace menginstal aplikasi Chat di ruang pesan langsung untuk pengguna di organisasi mereka. Untuk mempelajari aplikasi Chat yang diinstal oleh administrator, lihat Menginstal aplikasi Marketplace di domain Anda dalam dokumentasi Bantuan Admin Google Workspace.

 Aplikasi Chat mengirimkan pesan aktivasi yang menjelaskan fungsi aplikasi dan cara pengguna di ruang berinteraksi dengannya.
Kirim pesan

Pengguna berinteraksi dengan aplikasi Chat dalam pesan dengan salah satu cara berikut:

  • Mengirim pesan di ruang pesan langsung (DM) dengan aplikasi Chat.
  • @menyebut aplikasi Chat di semua jenis ruang.
  • Mengirim pesan yang berisi link yang cocok dengan pola URL untuk pratinjau link.
  • Mengetik teks ke dalam menu multiselect dari selectionInput widget.
 Aplikasi Chat merespons berdasarkan konten pesan. Misalnya, aplikasi Chat membalas perintah garis miring /about dengan pesan yang menjelaskan tugas yang dapat dilakukan aplikasi Chat.
Dihapus dari ruang

Pengguna menghapus aplikasi Chat dari ruang, atau administrator Google Workspace meng-uninstal aplikasi Chat untuk pengguna di organisasi mereka.

Pengguna tidak dapat menghapus aplikasi Chat yang diinstal oleh administrator mereka. Jika pengguna sebelumnya telah menginstal aplikasi Chat, aplikasi Chat tetap terinstal terlepas dari apakah administrator Google Workspace mencoba meng-uninstal.

 Aplikasi Chat akan menghapus notifikasi masuk yang dikonfigurasi untuk ruang (seperti menghapus webhook) dan menghapus penyimpanan internal. Aplikasi chat tidak dapat merespons dengan pesan pemicu ini, karena aplikasi tersebut bukan lagi anggota ruang.
Perintah aplikasi

Pengguna menggunakan perintah aplikasi Chat.

 Aplikasi Chat akan merespons perintah tersebut. Misalnya, membalas dengan pesan atau membuka dialog.
App Home

Pengguna membuka tab Beranda di ruang pesan langsung (DM) personal dengan aplikasi Chat, atau berinteraksi dengan widget di kartu halaman beranda.

 Aplikasi Chat menampilkan objek RenderActions yang mendorong kartu beranda (pushCard) atau memperbarui kartu beranda yang ditampilkan (updateCard).

Tidak seperti add-on lainnya, Anda harus mengonfigurasi fungsi callback untuk pemicu ini menggunakan Google Chat API. Untuk mendapatkan panduan, lihat Mengonfigurasi aplikasi Chat.

Untuk merespons pemicu, lihat panduan berikut:

Objek peristiwa

Aplikasi Chat menerima objek peristiwa saat pemicu Chat berjalan, atau saat pengguna Chat berinteraksi dengan UI dari aplikasi Chat (seperti mengklik tombol). 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, 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 juga mencakup 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, addedToSpacePayload, removedFromSpacePayload, buttonClickedPayload, widgetUpdatedPayload, atau appCommandPayload).

Untuk mempelajari cara menangani objek peristiwa, lihat panduan berikut:

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

Tindakan chat

Bagian ini menjelaskan cara aplikasi Chat dapat menggunakan tindakan add-on untuk merespons interaksi pengguna.

Untuk merespons dengan tindakan add-on, aplikasi Chat harus merespons dalam waktu 30 detik, dan respons harus diposting di ruang tempat interaksi terjadi. Jika tidak, aplikasi Chat harus menyiapkan autentikasi dan memanggil Google Chat API untuk merespons.

Aplikasi chat dapat menangani dan merespons interaksi dengan berbagai cara. Dalam banyak kasus, aplikasi Chat membalas dengan pesan. Aplikasi chat juga dapat mencari beberapa informasi dari sumber data, mencatat informasi objek peristiwa, atau melakukan hal lainnya. Perilaku pemrosesan ini pada dasarnya menentukan aplikasi Google Chat.

Untuk merespons interaksi pengguna, aplikasi Chat harus menangani objek peristiwa yang sesuai dan menampilkan salah satu objek JSON berikut:

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

Respons aplikasi chat Tindakan yang diperlukan untuk ditampilkan (JSON) Tindakan yang diperlukan untuk menampilkan (Apps Script)
Mengirim atau memperbarui pesan. DataActions DataActionsResponse
Merender atau memperbarui halaman beranda di tab Beranda dalam pesan langsung. RenderActions ActionResponse
Membuka, memperbarui, atau menutup dialog. RenderActions ActionResponse
Untuk mengumpulkan informasi dari kartu atau dialog, sarankan item pilihan berdasarkan apa yang diketik pengguna ke dalam menu multiselect. RenderActions ActionResponse
Pratinjau link dalam pesan yang dikirim pengguna Chat di ruang. DataActions DataActionsResponse

Memberikan respons menggunakan Google Chat API

Daripada menampilkan tindakan add-on, aplikasi Chat mungkin perlu menggunakan Google Chat API untuk merespons interaksi. Misalnya, aplikasi Chat harus memanggil Google Chat API untuk melakukan salah satu hal berikut:

  • Merespons interaksi setelah 30 detik.
  • Melakukan tugas di luar ruang tempat interaksi terjadi.
  • Menjalankan tugas di Chat yang tidak tersedia sebagai tindakan add-on. Misalnya, mencantumkan ruang tempat pengguna atau aplikasi Chat menjadi anggota, atau menambahkan pengguna ke ruang.
  • Melakukan tugas atas nama pengguna Chat (yang memerlukan autentikasi pengguna).

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

Node.js

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({});
};

Python

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 {}

Java

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 "{}";
}

Apps Script

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 mempelajari cara mengautentikasi dan memanggil Chat API, lihat Ringkasan Chat API.