Mengonfigurasi Google Chat API

Setiap aplikasi Google Chat yang Anda buat memerlukan project Google Cloud-nya sendiri dengan Chat API yang diaktifkan dan dikonfigurasi.

Untuk melakukan panggilan API hanya baca dengan autentikasi pengguna, seperti mendapatkan ruang dan mencantumkan pesan, Anda hanya perlu mengaktifkan API dan membuat klien OAuth.

Untuk melakukan panggilan API buat, perbarui, dan hapus, atau untuk men-deploy dan menguji aplikasi Chat interaktif (yang dibuat sebagai add-on Google Workspace yang memperluas Chat), Anda juga harus mengonfigurasi Chat API. Setelan konfigurasi Chat API adalah tempat Anda menentukan semua detail tentang aplikasi Chat, termasuk nama tampilan, avatar, endpoint deployment, dan fitur interaktifnya.

Prasyarat

Memilih nama tampilan, avatar, dan deskripsi untuk aplikasi Chat Anda

Saat mengaktifkan Chat API, Anda mengonfigurasi detail tentang aplikasi Chat yang muncul kepada pengguna di Chat, termasuk nama tampilan, avatar, dan deskripsi. Detail ini hanya muncul di Chat. Untuk memublikasikan aplikasi Chat ke Marketplace, Anda juga harus menentukan detail yang muncul di listingan Marketplace aplikasi Chat Anda.

Sebelum mengonfigurasi aplikasi Chat, siapkan informasi berikut:

Kolom Deskripsi Format
Nama aplikasi Nama tampilan untuk aplikasi Chat. Maksimal 25 karakter alfanumerik
URL avatar Gambar yang ditampilkan sebagai avatar aplikasi Chat Anda. URL HTTPS yang mengarah ke gambar grafis persegi (PNG atau JPEG). Ukuran yang direkomendasikan adalah 256x256 piksel atau lebih.
Deskripsi Deskripsi singkat tentang tujuan aplikasi Chat. Maksimal 40 karakter alfanumerik

Nama, avatar, dan deskripsi aplikasi Chat ditampilkan kepada pengguna di UI Chat. Untuk beberapa permintaan tulis Chat API, Chat menggunakan informasi ini untuk mengatribusikan tindakan yang dilakukan aplikasi Chat di Chat.

Misalnya, jika Anda memanggil metode spaces.create(), Chat akan menyertakan nama aplikasi Chat dalam deskripsi pembuat ruang, seperti yang ditunjukkan dalam gambar berikut:

Aplikasi Google Chat membuat ruang untuk pengguna.
Gambar 1. Pesan atribusi yang ditampilkan Chat saat metode spaces.create() digunakan untuk membuat ruang atas nama pengguna.

Untuk berinteraksi dengan aplikasi Chat, pengguna juga melihat atau menggunakan informasi ini dengan cara berikut:

  • @sebut aplikasi Chat untuk menambahkannya ke ruang atau mengirim pesan ke aplikasi tersebut.
  • Temukan dan mulai pesan langsung dengan aplikasi Chat. Di menu Aplikasi, pesan langsung menampilkan nama dan avatar aplikasi Chat.
  • Dari kolom tulis, pengguna dapat menjelajahi aplikasi Chat dan melihat nama, avatar, dan deskripsinya.

Mengonfigurasi aplikasi Chat di Konsol Google Cloud

Setelah Anda memiliki detail aplikasi Chat, buka project Cloud Anda dan konfigurasikan Chat API:

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

    Buka halaman Chat API Configuration

  2. Di bagian Application info, isi kolom App name, Avatar URL, dan Description.

  3. Opsional: Dari menu Sintaksis markup, pilih sintaksis markup default (Markdown atau Chat) untuk pesan aplikasi Chat Anda. Untuk mempelajari lebih lanjut pemformatan teks dan cara Chat menentukan sintaksis markup untuk permintaan API, lihat Memformat pesan.

  4. Di bagian Fitur interaktif, konfigurasikan apakah aplikasi Chat Anda merespons interaksi pengguna:

    Untuk membangun aplikasi Chat interaktif, aktifkan Enable interactive features dan selesaikan langkah-langkah berikut:

    1. Di bagian Functionality:
      • Opsional: Pilih Support App Home untuk menampilkan kartu halaman beranda di tab Home pesan langsung personal dengan aplikasi Chat.
      • Pilih Join spaces and group conversations agar aplikasi Chat Anda dapat diinstal dan digunakan. Secara default, pengguna dapat menginstal dan mengirim pesan dengan aplikasi Chat di ruang khusus antara pengguna dan aplikasi Chat. Pengguna juga dapat menambahkan dan berinteraksi dengan aplikasi Chat di ruang dengan beberapa orang.

    2. Di bagian Connection settings, pilih arsitektur yang ingin Anda gunakan untuk menerima objek peristiwa dari Chat:

      • Untuk menggunakan layanan HTTP, pilih HTTP endpoint URL dan berikan URL.
      • Untuk menggunakan project Google Apps Script, pilih Apps Script dan berikan ID deployment untuk project tersebut.
      • Untuk menggunakan agen Dialogflow, pilih Dialogflow, pilih Dialogflow CX atau Dialogflow ES, dan berikan nama resource agen.
      • Untuk menggunakan Pub/Sub, pilih Cloud Pub/Sub dan masukkan nama topik.

    3. Opsional: Untuk merutekan objek peristiwa ke endpoint atau fungsi tertentu, buka Connection settings > Triggers, lalu berikan atau perbarui endpoint atau fungsi callback untuk pemicu Chat berikut:

      • Beranda aplikasi (jika Dukung Beranda Aplikasi diaktifkan): Pengguna membuka tab Beranda di pesan langsung personal dengan aplikasi Chat.
      • Ditambahkan ke ruang: Pengguna menambahkan aplikasi Chat ke percakapan grup atau ruang, atau menginstal aplikasi Chat untuk pesan 1:1.
      • Pesan: Pengguna mengirim pesan ke aplikasi Chat. Misalnya, pengguna mengirim pesan langsung ke aplikasi Chat atau @menyebut aplikasi Chat di ruang dengan beberapa orang.
      • Dihapus dari ruang: Pengguna meng-uninstal atau menghapus aplikasi Chat dari ruang.
      • Perintah aplikasi: Pengguna memanggil perintah cepat, perintah garis miring, atau tindakan pesan dari aplikasi Chat.

    4. Opsional: Tambahkan fitur interaktif lainnya seperti perintah pemicu, perintah (perintah cepat, perintah garis miring, dan tindakan pesan), atau pratinjau link.

    5. Di bagian Visibility, tentukan alamat email Anda agar Anda dapat menginstal dan menguji aplikasi Chat sebelum memublikasikannya ke Google Workspace Marketplace. Anda dapat menentukan hingga lima individu, atau satu atau beberapa Google Grup dari organisasi Google Workspace Anda.

  5. Opsional: Di bagian Logs, centang kotak Log errors to Logging untuk menggunakan Google Cloud Logging. Untuk mengetahui informasi selengkapnya, lihat Membuat kueri log error untuk aplikasi Chat.

  6. Klik Simpan.

Setelah Anda menyimpan konfigurasi, siapa pun yang Anda tentukan di setelan Visibility Chat API dapat menginstal, menguji, atau menggunakan aplikasi Chat. Untuk mulai menguji dan men-debug aplikasi Chat, lihat Menguji fitur interaktif untuk aplikasi Google Chat.

Mengonfigurasi aplikasi Chat menggunakan Google Workspace Add-ons API

Daripada mengonfigurasi aplikasi Chat secara manual di Konsol Google Cloud, Anda dapat menggunakan project Google Cloud yang terdaftar dalam Program Pratinjau Developer Google Workspace untuk membaca dan memperbarui konfigurasi secara terprogram untuk aplikasi Chat yang dibuat sebagai add-on Google Workspace menggunakan resource chatAppConfig di Google Workspace add-ons API.

chatAppConfig adalah resource singleton yang selalu ada untuk setiap project Cloud. Sebelum Anda menyimpan konfigurasi untuk pertama kalinya, resource berisi konfigurasi kosong (yang juga ditampilkan oleh GetChatAppConfig jika Anda membaca resource sebelum penyimpanan pertama). Karena resource sudah ada, Anda tidak perlu membuatnya secara terpisah—gunakan UpdateChatAppConfig untuk menyimpan konfigurasi awal dan memperbarui konfigurasi yang ada.

Prasyarat dan autentikasi

Sebelum memanggil GetChatAppConfig atau UpdateChatAppConfig, selesaikan prasyarat berikut:

  1. Daftarkan project Google Cloud Anda ke Program Pratinjau Developer Google Workspace.
  2. Aktifkan Google Workspace add-ons API (gsuiteaddons.googleapis.com) di project Cloud Anda. Secara opsional, Anda dapat mengaktifkan Google Chat API (chat.googleapis.com) jika ingin melihat atau memperbarui konfigurasi aplikasi Chat di konsol Google Cloud atau memanggil Chat API.
  3. Lakukan autentikasi sebagai pengguna manusia dengan kredensial OAuth 2.0 yang menyertakan cakupan https://www.googleapis.com/auth/cloud-platform. Autentikasi akun layanan tidak didukung untuk metode chatAppConfig.
  4. Pastikan pengguna yang diautentikasi memiliki izin Identity and Access Management (IAM) yang diperlukan pada project Cloud target:
    • gsuiteaddons.chatAppConfigs.get dan chat.bots.get untuk membaca konfigurasi (GetChatAppConfig).
    • gsuiteaddons.chatAppConfigs.update dan chat.bots.update untuk mengupdate konfigurasi (UpdateChatAppConfig).
  5. Jika Anda menggunakan library klien, download library klien Pratinjau Developer dengan akun Pratinjau Developer yang terdaftar.

Memperbarui konfigurasi aplikasi Chat

Untuk mengonfigurasi aplikasi Chat untuk pertama kalinya atau mengupdate konfigurasi yang ada, kirim permintaan PATCH (UpdateChatAppConfig) ke resource chatAppConfig singleton untuk project Cloud Anda:

  • Untuk penyimpanan awal di project Cloud dengan chatAppConfig kosong, displayName (3 hingga 25 karakter) dan description (1 hingga 40 karakter) diperlukan. Jika Anda menghapus interactiveFeatureConfig pada penyimpanan awal, aplikasi Chat akan dikonfigurasi sebagai non-interaktif.
  • Untuk update berikutnya, gunakan parameter kueri updateMask opsional untuk menentukan kolom yang dipisahkan koma yang akan diupdate (atau hapus updateMask untuk mengupdate semua kolom yang disediakan). Memperbarui kolom berulang (appCommands, urlPatterns, atau allowlistedTestingPrincipals) akan menggantikan seluruh daftar.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

Ganti baris berikut di URL, header, dan isi permintaan:

  • PROJECT_NUMBER: Nomor project numerik dari project Cloud yang menghosting aplikasi Chat Anda.
  • ACCESS_TOKEN: Token akses OAuth 2.0 pengguna yang diizinkan dengan cakupan https://www.googleapis.com/auth/cloud-platform.
  • USER_EMAIL: Alamat email atau Grup Google dari organisasi Google Workspace Anda yang akan diizinkan untuk menguji aplikasi Chat (misalnya, alamat email Anda sendiri).
  • Contoh kolom konfigurasi dalam isi permintaan (seperti displayName, description, avatarUri, dan interactiveFeatureConfig, termasuk konfigurasi endpoint, perintah, pola URL pratinjau link, dan akun utama pengujian) dengan nilai untuk aplikasi Chat Anda. Untuk mengetahui detail tentang semua kolom dan opsi endpoint yang didukung, lihat referensi REST projects.chatAppConfig dan projects.chatAppConfig.patch.

Mendapatkan konfigurasi aplikasi Chat

Untuk membaca konfigurasi aplikasi Chat saat ini untuk project Cloud, panggil GetChatAppConfig. Anda dapat meneruskan parameter kueri view opsional (ChatAppConfigView):

  • BASIC (default): Menampilkan metadata dasar tanpa interactiveFeatureConfig.
  • FULL: Menampilkan semua kolom konfigurasi, termasuk interactiveFeatureConfig.

Jika konfigurasi aplikasi Chat belum disimpan untuk project Cloud, metode ini akan menampilkan objek ChatAppConfig kosong.

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

Pertimbangan untuk add-on Google Workspace yang sudah ada

Aplikasi Chat memerlukan konfigurasi yang berbeda dibandingkan dengan add-on Google Workspace yang memperluas aplikasi Google Workspace lainnya. Jika add-on Anda memperluas aplikasi Google Workspace lainnya, pertimbangkan persyaratan berikut untuk mengonfigurasi aplikasi Chat:

  • Baik pengguna perorangan maupun administrator Google Workspace harus dapat menginstal add-on Anda dari Marketplace. Anda mengonfigurasi setelan penginstalan ini di Marketplace SDK.
  • Aplikasi Chat tidak menggunakan nama dan logo yang Anda konfigurasi untuk aplikasi Google Workspace lainnya di objek addons.common manifes.
  • Untuk add-on yang dipublikasikan ke Google Workspace Marketplace, Anda tidak dapat menyimpan draf perubahan apa pun pada setelan konfigurasi Google Chat API. Setelah Anda memperbarui dan menyimpan setelan konfigurasi Chat API, aplikasi Chat yang diperbarui akan langsung tersedia untuk semua pengguna yang ada. Untuk memperbarui listingan Marketplace, Anda dapat membuat draf sebelum mengirimkan perubahan apa pun.
  • Jika Anda membuat add-on menggunakan Apps Script:
    • Anda harus menggunakan ID deployment Apps Script yang sama dengan yang Anda gunakan untuk konfigurasi add-on lainnya.
    • Anda tidak dapat menggunakan editor Apps Script untuk menginstal deployment pengujian di Chat. Sebagai gantinya, Anda harus menginstalnya langsung dari UI Chat.
  • Jika Anda membuat add-on menggunakan layanan HTTP, hilangkan detail konfigurasi aplikasi Chat dalam manifes projects.deployments yang Anda buat menggunakan Google Workspace Add-ons API. Deployment HTTP yang Anda tentukan di Google Workspace Marketplace SDK hanya digunakan untuk aplikasi Google Workspace lainnya. Sebagai gantinya, konfigurasikan aplikasi Chat Anda di Konsol Google Cloud atau menggunakan resource chatAppConfig di Google Workspace add-ons API.

Memberikan izin kepada orang lain untuk mengonfigurasi Chat API

Anda dapat memberi pengguna tertentu akses ke halaman konfigurasi aplikasi Chat dengan memberi mereka peran Google Cloud Identity Access Management (IAM) Pemilik aplikasi Chat atau Pelihat aplikasi Chat. Pengguna dengan peran ini tidak dapat membuka halaman konfigurasi aplikasi Chat menggunakan dasbor APIs & Services, tetapi dapat mengakses halaman konfigurasi dengan membuka Konsol Google Cloud untuk project Cloud host aplikasi Chat sebagai berikut:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

Dengan PROJECT_ID sebagai project ID dari project Google Cloud yang menghosting aplikasi Chat.

Aplikasi Chat yang bukan add-on: Mengonfigurasi Google Chat API

Jika Anda mengelola aplikasi Chat yang bukan add-on Google Workspace, konfigurasi Anda akan menggunakan satu endpoint untuk semua peristiwa interaksi, bukan pemicu per peristiwa:

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

    Buka halaman Konfigurasi Chat API

  2. Di bagian Interactive features, aktifkan Enable interactive features.

  3. Buat aplikasi Chat ini sebagai add-on Google Workspace. Dialog akan terbuka dan meminta Anda untuk mengonfirmasi. Pada dialog, klik Nonaktifkan.

  4. Di bagian Functionality, pilih Support App Home atau Join spaces and group conversations sesuai kebutuhan.

  5. Di bagian Connection settings, tentukan satu endpoint untuk aplikasi Chat Anda (HTTP endpoint URL, ID deployment Apps Script, Cloud Pub/Sub topic name, atau Dialogflow).

  6. Konfigurasikan Commands, Link previews, Visibility, dan Logs opsional, lalu klik Save.

Untuk mengupgrade aplikasi Chat yang bukan add-on ke add-on Google Workspace yang memperluas Google Chat, lihat Mengonversi aplikasi Google Chat menjadi add-on Google Workspace.