Membangun antarmuka Google Chat

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

Di Google Chat, add-on akan muncul kepada pengguna sebagai aplikasi Google Chat. Untuk mempelajari lebih lanjut, lihat Ringkasan memperluas Google Chat.

Untuk mem-build 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.
  • Dialog yang merupakan kartu yang terbuka di jendela baru dan biasanya meminta pengguna untuk mengirimkan informasi.
  • Pratinjau link yang merupakan kartu yang menampilkan pratinjau informasi tentang layanan eksternal.

Pemicu

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

Pemicu adalah cara spesifik 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 mengirim pesan orientasi yang menjelaskan fungsinya dan cara pengguna di ruang tersebut 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.
  • @mentions aplikasi Chat di jenis ruang apa pun.
  • Mengirim pesan yang berisi link yang cocok dengan pola URL untuk pratinjau link.
  • Mengetik teks ke dalam menu multi-pilih widget selectionInput.
 Aplikasi Chat merespons berdasarkan konten pesan. Misalnya, aplikasi Chat membalas perintah /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 organisasinya.

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

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

Pengguna menggunakan perintah cepat atau perintah garis miring dari aplikasi Chat.

 Aplikasi Chat merespons perintah. Misalnya, membalas dengan pesan atau membuka dialog.

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

Untuk merespons pemicu, lihat panduan berikut:

Objek peristiwa

Bagian ini menentukan dan menjelaskan semua elemen objek peristiwa Chat. Untuk mempelajari lebih lanjut, lihat Objek peristiwa.

Objek peristiwa
commonEventObject object (CommonEventObject)
Objek yang berisi informasi yang umum untuk semua objek peristiwa, terlepas dari aplikasi host.
chat object (Chat)
Objek yang berisi semua informasi tentang interaksi Chat.

Chat

Chat
chat.user object (User)
Pengguna Chat yang berinteraksi dengan aplikasi Chat.
chat.space object (Space)
Ruang Chat tempat pengguna berinteraksi dengan aplikasi Chat.
chat.eventTime

string (Timestamp format)

Waktu terjadinya interaksi.

Kolom union payload.

payload hanya dapat berupa salah satu dari hal berikut:
chat.messagePayload

object (MessagePayload)

Payload yang diterima aplikasi Chat dari pemicu Pesan.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Payload yang diterima aplikasi Chat dari pemicu Ditambahkan ke ruang.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Payload yang diterima aplikasi Chat dari pemicu Dihapus dari ruang.
chat.buttonClickedPayload

object (ButtonClickedPayload)

Payload yang diterima aplikasi Chat saat pengguna mengklik tombol dari pesan atau kartu. Jika pengguna mengklik tombol untuk mengirimkan informasi, objek commonEventObject.formInputs akan berisi nilai yang dikumpulkan dari pengguna. Untuk mengetahui detailnya, lihat Mengumpulkan informasi dari pengguna Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

Payload yang diterima aplikasi Chat saat pengguna mengetik teks ke dalam menu multipilih widget selectionInput. Aplikasi chat dapat menggunakan objek peristiwa ini untuk mengisi item yang disarankan dari sumber data dinamis. Misalnya, untuk mengisi kasus dukungan dari sumber data eksternal, aplikasi Chat dapat membuat kueri sumber data berdasarkan apa yang diketik pengguna ke dalam menu, lalu menampilkan kasus dukungan yang cocok sebagai item yang dapat dipilih.

Objek CommonEventObject.parameters['autocomplete_widget_query'] berisi nilai string yang diketik pengguna ke dalam menu.

chat.appCommandPayload

object (AppCommandPayload)

Payload yang diterima aplikasi Chat saat pengguna menggunakan perintah dari aplikasi Chat.

Payload

Bergantung pada jenis interaksi, peristiwa ini berisi payload dengan satu atau beberapa resource Chat API.

Payload pesan
MessagePayload
chat.messagePayload.message object (Message)
Pesan Chat yang memicu peristiwa.
chat.messagePayload.space object (Space)
Ruang Chat tempat pengguna mengirim pesan yang memanggil aplikasi Chat.

Ditambahkan ke payload ruang
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Ruang Chat tempat pengguna menambahkan atau menginstal aplikasi Chat.

Saat administrator menginstal aplikasi Chat, kolom space.adminInstalled ditetapkan ke true.

chat.addedToSpacePayload.interactionAdd boolean
Apakah pengguna menambahkan aplikasi Chat ke ruang menggunakan pesan. Misalnya, @mention aplikasi Chat atau menggunakan perintah garis miring. Jika true, Chat akan mengirim objek peristiwa lain dengan messagePayload yang berisi informasi tentang pesan.

Dihapus dari payload ruang
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
Ruang Chat tempat pengguna menghapus atau meng-uninstal aplikasi Chat.

Saat administrator meng-uninstal aplikasi Chat, kolom space.adminInstalled ditetapkan ke false.

Payload tombol diklik
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Pesan Chat yang berisi tombol yang diklik pengguna.
chat.buttonClickedPayload.space object (Space)
Ruang Chat tempat pengguna mengklik tombol dari pesan aplikasi Chat.
chat.buttonClickedPayload.isDialogEvent boolean
Apakah pengguna mengklik tombol untuk berinteraksi dengan dialog.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Jika isDialogEvent adalah true, jenis interaksi dalam dialog.

Enum DialogEventType.

Nilai dialogEventType hanya dapat berupa salah satu dari hal berikut:
TYPE_UNSPECIFIED Nilai default. Tidak ditentukan.
REQUEST_DIALOG Pengguna meminta dialog. Misalnya, mereka menggunakan perintah garis miring atau mengklik tombol dari pesan.
SUBMIT_DIALOG Pengguna mengklik elemen interaktif dalam dialog. Misalnya, pengguna mengisi informasi dalam dialog dan mengklik tombol untuk mengirimkan informasi.

Payload widget yang diperbarui
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Ruang Chat tempat interaksi terjadi.

Payload perintah aplikasi
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Metadata tentang perintah yang digunakan pengguna, dan cara mereka memicu perintah.
chat.appCommandPayload.space object (Space)
Ruang Chat tempat pengguna menggunakan perintah.
chat.appCommandPayload.thread object (Thread)
Jika interaksi terjadi dalam rangkaian pesan, rangkaian pesan Chat tempat pengguna menggunakan perintah.
chat.appCommandPayload.message object (Message)
Pesan yang dikirim pengguna dengan perintah garis miring.
chat.appCommandPayload.configCompleteRedirectUri string
Jika otorisasi atau konfigurasi diperlukan untuk perintah, URL yang akan dialihkan pengguna setelah mereka menyelesaikan proses di luar Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Apakah perintah membuka dialog.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Jenis interaksi dengan dialog.

Enum DialogEventType.

Nilai dialogEventType hanya dapat berupa salah satu dari hal berikut:
TYPE_UNSPECIFIED Nilai default. Tidak ditentukan.
REQUEST_DIALOG Pengguna meminta dialog. Misalnya, mereka menggunakan perintah garis miring atau mengklik tombol dari pesan.
SUBMIT_DIALOG Pengguna mengklik elemen interaktif dalam dialog. Misalnya, pengguna mengisi informasi dalam dialog dan mengklik tombol untuk mengirimkan informasi.
Metadata Perintah Aplikasi
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

ID perintah.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Jenis perintah.

Enum AppCommandType.

Nilai AppCommandType hanya dapat berupa salah satu dari hal berikut:
APP_COMMAND_TYPE_UNSPECIFIED Nilai default. Tidak ditentukan.
SLASH_COMMAND Pengguna menggunakan perintah dengan mengirim pesan yang diawali dengan garis miring /.

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 banyak cara. Dalam banyak kasus, aplikasi Chat akan membalas dengan pesan. Aplikasi chat juga dapat mencari beberapa informasi dari sumber data, mencatat informasi objek peristiwa, atau apa pun. Perilaku pemrosesan ini pada dasarnya adalah yang menentukan aplikasi Google Chat.

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

Respons yang diinginkan aplikasi Chat Tindakan yang diperlukan untuk kembali
Mengirim atau memperbarui pesan. DataActions
Membuka, memperbarui, atau menutup dialog. RenderActions
Untuk mengumpulkan informasi dari kartu atau dialog, sarankan item pilihan berdasarkan apa yang diketik pengguna ke dalam menu multipilih. RenderActions
Pratinjau link dalam pesan yang dikirim pengguna Chat di ruang. DataActions

Merespons 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.
  • Melakukan tugas di Chat yang tidak tersedia sebagai tindakan add-on. Misalnya, cantumkan ruang yang menjadi anggota pengguna atau aplikasi Chat, atau tambahkan pengguna ke ruang.
  • Melakukan tugas atas nama pengguna Chat (yang memerlukan autentikasi pengguna).

Untuk mempelajari cara mengautentikasi dan memanggil Chat API, lihat ringkasan Chat API.