Menggunakan acara dari Google Chat

Halaman ini menjelaskan cara aplikasi Google Chat dapat menerima dan merespons peristiwa di Google Chat.

Peristiwa Google Chat mewakili aktivitas atau perubahan di Chat, seperti pesan baru di ruang. Aplikasi Chat Anda dapat menggunakan peristiwa untuk memahami apa yang terjadi dan mengambil tindakan atau merespons dengan cara yang bermakna bagi pengguna Anda.

Berikut beberapa contoh cara Anda dapat menggunakan peristiwa:

• Memantau dan merespons pesan baru di ruang, seperti memeriksa kata kunci atau frasa.
• Mengirim pesan sambutan kepada pengguna saat mereka bergabung ke ruang, untuk menjelaskan panduan ruang atau membagikan tips tentang cara menggunakan aplikasi Chat secara efektif.
• Melacak dan menganalisis aktivitas Chat. Misalnya, untuk mengirim laporan bulanan tentang anggota baru atau pesan yang mendapatkan reaksi atau balasan terbanyak.
• Berkomunikasi di seluruh platform pesan. Misalnya, pengguna dapat mengirim dan menerima pesan dari pengguna di platform pesan yang berbeda tanpa keluar dari Chat.

Cara kerja peristiwa

Setiap kali sesuatu terjadi di Google Chat, resource Google Chat API akan dibuat, diperbarui, atau dihapus. Chat menggunakan peristiwa untuk mengirimkan informasi ke aplikasi Chat Anda tentang jenis aktivitas yang terjadi, dan resource Chat API yang terpengaruh.

Gambar 1. Pengguna memposting pesan di ruang Chat, yang membuat resource Message. Chat kemudian membuat peristiwa yang berisi data tentang pesan baru pesan.

Chat mengategorikan peristiwa berdasarkan jenis. Jenis peristiwa membantu Anda memfilter dan hanya menerima jenis informasi yang Anda butuhkan, serta memungkinkan Anda menangani aktivitas serupa dengan cara yang sama.

Tabel berikut menunjukkan bagaimana aktivitas di Chat memengaruhi resource Chat API terkait, dan jenis peristiwa yang diterima aplikasi Chat Anda:

Aktivitas	Resource Chat API	Jenis peristiwa
Pengguna memposting pesan di ruang Chat	Resource Message dibuat.	Pesan baru
Pengguna menjadi pengelola ruang.	Resource Membership diperbarui.	Keanggotaan diperbarui
Pengguna bereaksi terhadap pesan.	Resource Reaction dibuat.	Reaksi baru
Pengguna keluar dari ruang.	Resource Membership dihapus.	Keanggotaan dihapus

Catatan: Aplikasi Chat Anda juga dapat menerima peristiwa interaksi. Peristiwa ini membantu Anda merespons interaksi pengguna langsung, seperti saat pengguna menambahkan aplikasi Chat Anda ke ruang atau @menyebut aplikasi Chat Anda. Untuk mengonfigurasi dan menerima peristiwa interaksi, lihat Menerima dan merespons interaksi dengan aplikasi Google Chat Anda.

Menerima peristiwa dari Google Chat

Untuk menerima peristiwa, aplikasi Chat Anda dapat melakukan salah satu hal berikut:

• Berlangganan peristiwa menggunakan Google Workspace Events API untuk menerima peristiwa saat terjadi.
• Mengirim kueri untuk peristiwa terbaru dengan memanggil Chat API.

Tabel berikut menjelaskan perbedaan dan alasan untuk mengirim kueri atau berlangganan peristiwa:

	Berlangganan peristiwa	Mengirim kueri untuk peristiwa
Kasus penggunaan	Memproses atau merespons peristiwa secara real time. Memantau aktivitas keanggotaan pengguna dan menemukan ruang baru untuk dipantau.	Memproses atau merespons peristiwa secara berkala, atau melalui pemicu. Mengambil peristiwa yang terlewat dari langganan (karena gangguan atau langganan tidak aktif).
API	Google Workspace Events API	Chat API
Sumber peristiwa	Ruang, pengguna, dan organisasi Google Workspace ( Pratinjau Developer)	Hanya ruang
Peristiwa yang didukung	Pesan Keanggotaan Reaksi Ruang Untuk mengetahui daftar jenis peristiwa yang didukung, lihat Jenis peristiwa untuk membuat langganan di dokumentasi Google Workspace Events API.	Pesan Keanggotaan Reaksi Ruang Untuk mengetahui daftar jenis peristiwa yang didukung, lihat resource spaceEvents di dokumentasi referensi Chat API.
Format peristiwa	Pesan Google Cloud Pub/Sub, yang diformat sesuai dengan spesifikasi CloudEvent. Untuk mengetahui detailnya, lihat Struktur peristiwa Google Workspace.	Resource Chat API ( spaces.spaceEvent)
Data peristiwa	String berenkode Base64 dengan atau tanpa data resource. Untuk mengetahui contoh payload, lihat Data peristiwa.	Payload JSON yang berisi data resource. Beberapa jenis peristiwa hanya menyertakan kolom resource tertentu. Untuk mengetahui contoh payload, lihat dokumentasi referensi.

Contoh: Mengirim kueri atau berlangganan peristiwa tentang keanggotaan di ruang

Dalam contoh ini, aplikasi Chat ingin menerima informasi tentang perubahan pada anggota ruang Chat. Di ruang, aktivitas keanggotaan berikut terjadi:

• Pengguna bergabung ke ruang, yang membuat resource Membership dan memicu peristiwa anggota baru.
• Pengguna menjadi pengelola ruang, yang memperbarui resource Membership untuk pengguna dan memicu peristiwa anggota yang diperbarui.
• Pengguna keluar dari ruang, yang menghapus resource Membership untuk pengguna dan memicu peristiwa anggota yang dihapus.

Berlangganan peristiwa keanggotaan

Untuk menerima peristiwa secara real time, aplikasi Chat memanggil subscriptions.create() metode Google Workspace Events API untuk berlangganan ruang untuk semua jenis peristiwa keanggotaan. Setelah membuat langganan, aplikasi Chat dapat mulai menerima peristiwa keanggotaan.

Gambar 2. Aplikasi Chat menerima peristiwa keanggotaan melalui langganan menggunakan Google Workspace Events API.

Pada gambar 2, aplikasi Chat memiliki langganan aktif ke ruang, sehingga aplikasi menerima peristiwa setiap kali keanggotaan di ruang berubah. Aplikasi Chat kemudian dapat memproses atau merespons secara real time aktivitas apa pun, seperti memposting pesan sambutan pribadi kepada anggota yang bergabung ke ruang.

Untuk mempelajari cara membuat langganan menggunakan Google Workspace Events API, lihat dokumentasi Google Workspace Events API.

Mengirim kueri untuk peristiwa keanggotaan terbaru

Daripada menerima peristiwa keanggotaan saat terjadi, aplikasi Chat dapat memanggil Chat API untuk mencantumkan peristiwa ruang terbaru yang terkait dengan aktivitas keanggotaan.

Gambar 3. Aplikasi Chat menerima peristiwa keanggotaan terbaru dengan mengirim kueri untuk peristiwa ruang menggunakan Chat API.

Pada gambar 3, aplikasi Chat memanggil metode Chat API spaces.spaceEvents.list() setelah semua aktivitas keanggotaan terjadi, dan memfilter kueri untuk peristiwa keanggotaan baru, diperbarui, dan dihapus. Chat API menampilkan daftar resource spaceEvent yang mewakili setiap perubahan keanggotaan. Aplikasi Chat kemudian dapat memproses atau merespons berdasarkan aktivitas terbaru, seperti memposting pesan mingguan dengan ringkasan aktivitas keanggotaan ruang dalam 7 hari terakhir.

Untuk mengirim kueri untuk peristiwa menggunakan Chat API, lihat Mencantumkan peristiwa dari ruang Google Chat.

Batasan dan perilaku pengiriman

Batasan umum

• Untuk menerima peristiwa keanggotaan, pengguna atau aplikasi Chat harus menjadi anggota langsung ruang. Jika mereka ditambahkan, diperbarui, atau dihapus secara tidak langsung ke ruang melalui Grup Google, langganan tidak akan menerima peristiwa keanggotaan tersebut. Untuk memahami cara kerja keanggotaan Grup Google, lihat Menambahkan Grup Google ke ruang.

Langganan pengguna

• Untuk langganan pengguna, peristiwa tentang anggota baru dalam pesan langsung atau chat grup tanpa nama (google.workspace.chat.membership.v1.created), hanya akan dipicu setelah pesan pertama diposting.

Langganan pelanggan ( Pratinjau Developer)

Untuk langganan pelanggan, batasan berikut berlaku:

• Organisasi Google Workspace harus memiliki setidaknya satu lisensi SKU Enterprise. Perhatikan bahwa persyaratan ini tidak akan diterapkan secara ketat selama tahap Program Pratinjau Developer, tetapi akan diterapkan di masa mendatang (akan diumumkan secara terpisah).
• Aplikasi Chat hanya dapat membuat satu langganan pelanggan untuk organisasi Google Workspace tertentu. Organisasi Google Workspace dapat memiliki maksimal lima langganan pelanggan secara total (dibuat oleh aplikasi Chat yang berbeda).

Untuk langganan pelanggan, pengiriman peristiwa mengikuti aturan umum berikut:

• Peristiwa ruang: Hanya dikirim jika peristiwa terjadi di ruang yang dikelola oleh organisasi Google Workspace Anda.
• Peristiwa pengguna: Hanya dikirim jika peristiwa terjadi untuk pengguna yang tergabung dalam organisasi Google Workspace Anda.

Satu-satunya pengecualian untuk aturan ini adalah untuk peristiwa keanggotaan. Langganan Anda dapat menerima peristiwa keanggotaan dari ruang yang dikelola oleh organisasi Anda dan ruang yang dikelola oleh organisasi eksternal, tetapi cara pengirimannya bergantung pada organisasi yang mengelola ruang:

Ruang yang dikelola oleh organisasi Google Workspace Anda

Jika perubahan keanggotaan terjadi di ruang yang dikelola oleh organisasi Google Workspace, perubahan tersebut akan dikirim sebagai peristiwa ruang.

Nama resource peristiwa ruang menggunakan format berikut:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Ruang yang dikelola oleh organisasi eksternal

Jika keanggotaan pengguna yang dikelola oleh organisasi Google Workspace Anda berubah di ruang yang dikelola oleh organisasi eksternal (misalnya, ruang bernama eksternal atau pesan langsung yang dibuat oleh pengguna eksternal), langganan Anda akan menerima peristiwa ini sebagai peristiwa pengguna.

Nama resource peristiwa pengguna menggunakan format berikut:

users/{userId}/userEvents/{userEventId}

Topik terkait

• Ringkasan Google Workspace Events API
• Membuat langganan
• Mendapatkan detail tentang peristiwa ruang Google Chat
• Mencantumkan peristiwa dari ruang Google Chat