Menerima dan merespons interaksi pengguna

Halaman ini menjelaskan cara aplikasi Google Chat Anda dapat menerima dan merespons interaksi pengguna, yang juga dikenal sebagai peristiwa interaksi aplikasi Google Chat.

Halaman ini menjelaskan cara melakukan hal berikut:

• Konfigurasikan aplikasi Chat Anda untuk menerima peristiwa interaksi.
• Proses peristiwa interaksi di infrastruktur Anda.
• Jika sesuai, respons peristiwa interaksi.

Mem-build aplikasi Chat interaktif sebagai add-on Google Workspace

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

Untuk mem-build aplikasi Chat yang berinteraksi dengan pengguna Chat, Anda dapat mem-build add-on Google Workspace yang memperluas Chat. Aplikasi Chat menerima dan merespons objek peristiwa add-on, bukan menerima peristiwa interaksi dari Chat API. Untuk mempelajari lebih lanjut, lihat Memperluas Google Chat dalam dokumentasi add-on Google Workspace.

Prasyarat

Aplikasi Google Chat yang diaktifkan untuk fitur interaktif. Untuk membuat aplikasi Chat interaktif, selesaikan salah satu panduan memulai berikut berdasarkan arsitektur aplikasi yang ingin Anda gunakan:

• Layanan HTTP dengan Google Cloud Functions
• Google Apps Script
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

Jenis peristiwa interaksi

Peristiwa interaksi aplikasi Google Chat mewakili tindakan apa pun yang dilakukan pengguna untuk memanggil atau berinteraksi dengan aplikasi Chat, seperti @menyebutkan aplikasi Chat atau menambahkannya ke ruang.

Saat pengguna berinteraksi dengan aplikasi Chat, Google Chat akan mengirimkan peristiwa interaksi ke aplikasi Chat, yang direpresentasikan sebagai jenis Event di Chat API. Aplikasi Chat dapat menggunakan peristiwa untuk memproses interaksi, dan secara opsional, merespons dengan pesan.

Untuk setiap jenis interaksi pengguna, Google Chat mengirimkan jenis peristiwa interaksi yang berbeda yang membantu aplikasi Chat Anda menangani setiap jenis peristiwa dengan semestinya. Jenis peristiwa interaksi direpresentasikan menggunakan objek eventType.

Misalnya, Google Chat menggunakan jenis peristiwa ADDED_TO_SPACE untuk interaksi apa pun saat pengguna menambahkan aplikasi Chat ke ruang, sehingga aplikasi Chat dapat segera merespons dengan pesan selamat datang di ruang.

Gambar 1: Saat pengguna menambahkan aplikasi Chat ke ruang, aplikasi Chat akan menerima peristiwa interaksi ADDED_TO_SPACE yang ditangani aplikasi Chat untuk mengirim pesan selamat datang di ruang.

Tabel berikut menunjukkan interaksi pengguna umum, jenis peristiwa interaksi yang diterima aplikasi Chat, dan cara aplikasi Chat biasanya merespons:

Interaksi pengguna	eventType	Respons umum dari aplikasi Chat
Pengguna memanggil aplikasi Chat dengan @menyebutkannya atau menggunakan perintah garis miring.	MESSAGE	Aplikasi Chat merespons berdasarkan konten pesan. Misalnya, aplikasi Chat membalas perintah /about dengan pesan yang menjelaskan tugas yang dapat dilakukan aplikasi Chat.
Pengguna menambahkan aplikasi Chat ke ruang.	ADDED_TO_SPACE	Aplikasi Chat mengirim pesan orientasi yang menjelaskan fungsinya dan cara pengguna di ruang berinteraksi dengannya.
Pengguna menghapus aplikasi Chat dari ruang.	REMOVED_FROM_SPACE	Aplikasi Chat akan menghapus notifikasi masuk yang dikonfigurasi untuk ruang (seperti menghapus webhook) dan mengosongkan penyimpanan internal.
Pengguna mengklik tombol di kartu dari pesan, dialog, atau halaman beranda aplikasi Chat.	CARD_CLICKED	Aplikasi Chat memproses dan menyimpan data apa pun yang dikirimkan pengguna, atau menampilkan kartu lain.
Pengguna membuka halaman beranda aplikasi Chat dengan mengklik tab Beranda dalam pesan 1:1.	APP_HOME	Aplikasi Chat menampilkan kartu statis atau interaktif dari halaman beranda.
Pengguna mengirimkan formulir dari halaman beranda aplikasi Chat.	SUBMIT_FORM	Aplikasi Chat memproses dan menyimpan data apa pun yang dikirimkan pengguna, atau menampilkan kartu lain.

Untuk melihat semua peristiwa interaksi yang didukung, lihat dokumentasi referensi EventType.

Peristiwa interaksi dari dialog

Jika aplikasi Chat Anda membuka dialog, peristiwa interaksi akan berisi informasi tambahan berikut yang dapat Anda gunakan untuk memproses respons:

• isDialogEvent disetel ke true.
• DialogEventType menjelaskan apakah interaksi memicu dialog untuk terbuka, mengirimkan informasi dari dialog, atau menutup dialog.

Tabel berikut menunjukkan interaksi umum dengan dialog, jenis peristiwa dialog yang sesuai, dan deskripsi cara aplikasi Chat biasanya merespons:

Interaksi pengguna dengan dialog	Jenis peristiwa dialog	Respons umum
Pengguna memicu permintaan dialog. Misalnya, mereka menggunakan perintah garis miring atau mengklik tombol dari pesan.	REQUEST_DIALOG	Aplikasi Chat akan membuka dialog.
Pengguna mengirimkan informasi dalam dialog dengan mengklik tombol.	SUBMIT_DIALOG	Aplikasi Chat akan membuka dialog lain atau menutup dialog untuk menyelesaikan interaksi.
Pengguna keluar atau menutup dialog sebelum mengirimkan informasi.	CANCEL_DIALOG	Secara opsional, aplikasi Chat dapat merespons dengan pesan baru, atau memperbarui pesan atau kartu tempat pengguna membuka dialog.

Untuk mengetahui informasi selengkapnya, lihat Membuka dialog interaktif.

Menerima peristiwa interaksi aplikasi Chat

Bagian ini menjelaskan cara menerima dan memproses peristiwa interaksi untuk aplikasi Chat Anda.

Mengonfigurasi aplikasi Chat untuk menerima peristiwa interaksi

Tidak semua aplikasi Chat bersifat interaktif. Misalnya, webhook masuk hanya dapat mengirim pesan keluar dan tidak dapat merespons pengguna. Jika membuat aplikasi Chat interaktif, Anda harus memilih endpoint yang memungkinkan aplikasi Chat menerima, memproses, dan merespons peristiwa interaksi. Untuk mempelajari lebih lanjut cara mendesain aplikasi Chat, lihat Arsitektur penerapan aplikasi Chat.

Untuk setiap fitur interaktif yang ingin Anda buat, Anda harus memperbarui konfigurasi di Chat API agar Google Chat dapat mengirim peristiwa interaksi terkait ke aplikasi Chat Anda:

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

   Buka halaman Konfigurasi Chat API

2. Di bagian Fitur interaktif, tinjau setelan dan perbarui berdasarkan fitur yang ingin Anda build:

   Kolom	Deskripsi
   Fungsi	Wajib. Kumpulan kolom yang menentukan cara aplikasi Chat dapat berinteraksi dengan pengguna: Menerima pesan 1:1: Pengguna dapat menemukan dan mengirim pesan ke aplikasi Chat langsung di Google Chat. Bergabung ke ruang dan percakapan grup: Pengguna dapat menambahkan aplikasi Chat ke ruang dan percakapan grup.
   Setelan koneksi	Wajib. Endpoint untuk aplikasi Chat, yang merupakan salah satu dari berikut ini: URL endpoint HTTP: Endpoint HTTPS yang menghosting implementasi aplikasi Chat. Apps Script: ID deployment untuk project Apps Script yang mengimplementasikan aplikasi Chat. Nama topik Cloud Pub/Sub: Topik Pub/Sub yang dilanggani aplikasi Chat sebagai endpoint. Dialogflow: Mendaftarkan aplikasi Chat dengan integrasi Dialogflow. Untuk mengetahui informasi selengkapnya, lihat Mem-build aplikasi Google Chat Dialogflow yang memahami bahasa alami.
   Perintah garis miring	Opsional. Perintah yang dapat ditampilkan kepada pengguna dalam Google Chat. Memungkinkan pengguna melihat tindakan inti untuk aplikasi Chat Anda dalam Google Chat, dan memilih tindakan tertentu yang ingin mereka gunakan untuk berinteraksi. Untuk mengetahui informasi selengkapnya, lihat Merespons perintah garis miring sebagai aplikasi Chat.
   Pratinjau link	Opsional. Pola URL yang dikenali aplikasi Chat dan menyediakan konten tambahan saat pengguna mengirim link. Untuk informasi selengkapnya, lihat Link pratinjau.
   Visibilitas	Opsional. Maksimal lima individu, atau satu atau beberapa Google Grup yang dapat melihat dan menginstal aplikasi Chat Anda. Gunakan kolom ini untuk menguji aplikasi Chat, atau untuk membagikan aplikasi Chat kepada tim Anda. Untuk informasi selengkapnya, lihat Menguji fitur interaktif.

3. Klik Simpan. Saat Anda menyimpan konfigurasi aplikasi Chat, aplikasi Chat akan tersedia untuk pengguna yang ditentukan di organisasi Google Workspace Anda.

Aplikasi Chat Anda kini dikonfigurasi untuk menerima peristiwa interaksi dari Google Chat.

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 akan mencoba mengirim ulang beberapa kali dalam beberapa menit (tetapi hal ini tidak dijamin). Akibatnya, aplikasi Chat mungkin menerima pesan yang sama beberapa kali dalam situasi tertentu. Jika permintaan berhasil diselesaikan, tetapi menampilkan payload pesan yang tidak valid, Google Chat tidak akan mencoba lagi permintaan tersebut.

Memproses atau merespons peristiwa interaksi

Bagian ini menjelaskan cara aplikasi Google Chat memproses dan merespons peristiwa interaksi.

Setelah aplikasi Chat menerima peristiwa interaksi dari Google Chat, aplikasi dapat merespons dengan banyak cara. Dalam banyak kasus, aplikasi Chat interaktif membalas pengguna dengan pesan. Aplikasi Google Chat juga dapat mencari beberapa informasi dari sumber data, mencatat informasi peristiwa interaksi, atau apa pun. Perilaku pemrosesan ini pada dasarnya adalah yang menentukan aplikasi Google Chat.

Untuk merespons secara sinkron, aplikasi Chat harus merespons dalam waktu 30 detik, dan respons harus diposting di ruang tempat interaksi terjadi. Jika tidak, aplikasi Chat dapat merespons secara asinkron.

Untuk setiap peristiwa interaksi, aplikasi Chat menerima isi permintaan, yang merupakan payload JSON yang mewakili peristiwa tersebut. Anda dapat menggunakan informasi tersebut untuk memproses respons. Untuk contoh payload peristiwa, lihat Jenis peristiwa interaksi aplikasi Chat.

Diagram berikut menunjukkan cara aplikasi Google Chat biasanya memproses atau merespons berbagai jenis peristiwa interaksi:

Tampilkan respons secara real time

Peristiwa interaksi memungkinkan aplikasi Chat merespons secara real time, atau sinkron. Respons sinkron tidak memerlukan autentikasi.

Untuk merespons secara real time, aplikasi Chat harus menampilkan objek Message. Untuk membalas dengan pesan di ruang, objek Message dapat berisi objek text, cardsV2, dan accessoryWidgets. Untuk digunakan dengan jenis respons lainnya, lihat panduan berikut:

• Membuka dialog interaktif
• Pratinjau link
• Memproses informasi yang dikirimkan oleh pengguna

Catatan: Untuk peristiwa interaksi REMOVED_FROM_SPACE, aplikasi Chat tidak dapat merespons dengan objek Message karena tidak lagi berada di ruang.

Balas dengan pesan

Dalam contoh ini, aplikasi Chat Anda akan membuat dan mengirim pesan teks setiap kali ditambahkan ke ruang. Untuk mempelajari praktik terbaik dalam melakukan orientasi kepada pengguna, lihat Memperkenalkan aplikasi Chat kepada pengguna.

Untuk mengirim pesan teks saat pengguna menambahkan aplikasi Chat Anda ke ruang, aplikasi Chat Anda akan merespons peristiwa interaksi ADDED_TO_SPACE. Untuk merespons peristiwa interaksi ADDED_TO_SPACE dengan pesan teks, gunakan kode berikut:

Node.js

/**
 * 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // 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`.'
    });
  }
};

Apps Script

/**
 * 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
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`.'
  }
}

Contoh kode menampilkan pesan teks berikut:

Merespons secara asinkron

Terkadang aplikasi Chat harus merespons peristiwa interaksi setelah 30 detik atau melakukan tugas di luar ruang tempat peristiwa interaksi dibuat. Misalnya, aplikasi Chat mungkin perlu merespons pengguna setelah menyelesaikan tugas yang berjalan lama. Dalam hal ini, aplikasi Chat dapat merespons secara asinkron dengan memanggil Google Chat API.

Untuk membuat pesan menggunakan Chat API, lihat Membuat pesan. Untuk panduan tentang cara menggunakan metode Chat API tambahan, lihat ringkasan Chat API.

Topik terkait

• Mengirim pesan
• Membuka dialog interaktif
• Pratinjau link
• Membaca input data formulir oleh pengguna di kartu
• Merespons perintah garis miring
• Mem-build halaman beranda untuk aplikasi Chat
• Memverifikasi permintaan dari Chat
• Menguji fitur interaktif untuk aplikasi Google Chat