Menerima dan merespons interaksi dengan aplikasi Google Chat Anda

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

Peristiwa interaksi aplikasi Google Chat mewakili tindakan apa pun yang dilakukan pengguna untuk memanggil atau berinteraksi dengan aplikasi Chat, seperti @menyebut aplikasi Chat atau menambahkannya ke ruang. Saat pengguna berinteraksi dengan aplikasi Chat, Google Chat mengirimkan peristiwa interaksi ke aplikasi Chat. Aplikasi Chat dapat menggunakan peristiwa untuk memproses interaksi dan membuat respons.

Misalnya, aplikasi Chat menggunakan peristiwa interaksi untuk melakukan salah satu dari hal berikut:

Untuk setiap jenis interaksi pengguna, Google Chat mengirimkan jenis peristiwa interaksi yang berbeda. Misalnya, Google Chat menggunakan jenis peristiwa MESSAGE untuk interaksi apa pun saat pengguna memanggil aplikasi Chat dalam pesan. Untuk mengetahui detailnya, lihat Jenis peristiwa interaksi aplikasi Google Chat.

Halaman ini menjelaskan cara melakukan hal berikut:

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

Menerima peristiwa interaksi aplikasi Chat

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

Mengonfigurasi aplikasi Chat Anda untuk menerima peristiwa interaksi

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

Jika telah membangun aplikasi Chat interaktif, Anda harus mengonfigurasi Google Chat API agar Google Chat dapat mengirimkan peristiwa interaksi:

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

   Buka halaman Google Chat API

2. Klik tab Configuration.
3. Di bagian Fitur interaktif, klik tombol Aktifkan fitur interaktif ke posisi aktif.
4. Di Functionality, pilih salah satu atau kedua kotak centang berikut:
   1. Menerima pesan 1:1: Memungkinkan pengguna berinteraksi dengan aplikasi Chat Anda di ruang pesan langsung (DM). Aplikasi Chat Anda menerima peristiwa interaksi setiap kali pengguna mengirim pesan di ruang DM.
   2. Bergabung ke ruang dan percakapan grup: Memungkinkan pengguna menambahkan dan menghapus aplikasi Chat Anda ke ruang yang berisi lebih dari satu orang. Aplikasi Chat Anda menerima peristiwa interaksi setiap kali ditambahkan atau dihapus dari ruang, dan setiap kali pengguna @menyebut atau menggunakan perintah garis miring di ruang.
5. Di Setelan koneksi, tentukan tujuan pengiriman peristiwa interaksi aplikasi Chat oleh Google Chat.
6. Opsional: Di Perintah garis miring, tambahkan dan konfigurasi satu atau beberapa perintah garis miring. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan perintah garis miring.
7. Opsional: Di Pratinjau link, tambahkan dan konfigurasi satu atau beberapa pola URL yang dipratinjau aplikasi Chat Anda. Untuk informasi selengkapnya, lihat Link pratinjau.
8. Klik Simpan.

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

Mengautentikasi permintaan dari Google Chat

Untuk aplikasi yang di-build di endpoint HTTP, bagian ini menjelaskan cara memverifikasi bahwa permintaan ke endpoint Anda berasal dari Google Chat.

Untuk mengirim peristiwa interaksi ke endpoint aplikasi Chat Anda, Google akan membuat permintaan ke layanan Anda. Untuk memverifikasi bahwa permintaan berasal dari Google, Google Chat menyertakan token pemilik di header Authorization setiap permintaan HTTPS ke endpoint Anda. Contoh:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

String AbCdEf123456 dalam contoh di atas adalah token otorisasi pembawa. Ini adalah token kriptografis yang dibuat oleh Google. Anda dapat memverifikasi token pembawa menggunakan library klien Google API open source:

• Java: https://github.com/google/google-api-java-client
• Python: https://github.com/google/google-api-python-client
• .NET: https://github.com/google/google-api-dotnet-client

Untuk token pemilik yang dikirim dalam permintaan Google Chat, penerbitnya adalah chat@system.gserviceaccount.com dan kolom audience ditetapkan ke jumlah project Google Cloud yang Anda gunakan untuk mem-build aplikasi Chat. Misalnya, jika nomor project Cloud aplikasi Chat Anda adalah 1234567890, maka kolom audience di token pemilik adalah 1234567890.

Jika token tidak memverifikasi untuk aplikasi Chat, layanan Anda harus merespons permintaan dengan kode respons HTTPS 401 (Unauthorized).

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

Menangani percobaan ulang panggilan HTTP ke layanan

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 kembali pengiriman 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 dapat memproses dan merespons peristiwa interaksi.

Setelah menerima peristiwa interaksi dari Google Chat, aplikasi Chat Anda 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, merekam informasi peristiwa interaksi, atau apa pun lainnya. Perilaku pemrosesan ini pada dasarnya adalah hal yang mendefinisikan aplikasi Google Chat.

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 mengetahui 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 secara sinkron. Respons sinkron tidak memerlukan autentikasi.

Untuk membuat respons sinkron terhadap peristiwa interaksi, lihat panduan berikut:

• Membuat pesan kartu
• Membuat pesan teks
• Membuka dialog interaktif
• Link pratinjau
• Membaca input data formulir oleh pengguna di kartu
• Menyiapkan perintah garis miring

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.

Merespons secara asinkron

Terkadang aplikasi Chat harus merespons peristiwa interaksi setelah 30 detik atau menjalankan 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 penggunaan metode Chat API tambahan, lihat Ringkasan Chat API.