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 Anda 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.

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 256 x 256 piksel atau lebih.
Deskripsi Deskripsi singkat aplikasi Chat, yang ditampilkan saat pengguna menelusuri aplikasi di Chat. Maksimal 40 karakter alfanumerik
Deskripsi panjang Opsional. Deskripsi tentang hal yang dapat dilakukan aplikasi Chat, yang ditampilkan saat pengguna memulai percakapan dengan aplikasi Chat atau membuka halaman beranda sesi untuk agen. Saat ini hanya didukung saat mengupdate konfigurasi aplikasi menggunakan Konsol Google Cloud dan tidak didukung melalui Google Workspace add-ons API. Maksimal 250 karakter

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 tentang siapa yang membuat ruang, seperti yang ditunjukkan pada 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: Isi kolom Deskripsi panjang.

  4. 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.

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

    Untuk membuat 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 Dukungan Beranda Aplikasi diaktifkan): Pengguna membuka tab Beranda dalam 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 sesi, perintah pemicu, perintah (perintah cepat, perintah garis miring, dan tindakan pesan), atau pratinjau link.

    5. Di bagian Visibility, pilih Make this Chat app available to specific people and groups dan masukkan alamat email individu atau Google Grup di organisasi Google Workspace Anda:

      • Untuk menginstal dan menguji aplikasi sendiri, masukkan alamat email Anda sendiri.
      • Untuk membagikan aplikasi Chat internal ke seluruh tim atau seluruh organisasi tanpa memublikasikannya ke Marketplace, masukkan satu atau beberapa Grup Google. Grup tidak memiliki batas anggota. Jika aplikasi Anda meminta cakupan chat.app.*, Anda tetap harus memublikasikan aplikasi untuk mendapatkan persetujuan administrator.
      • Jika administrator Anda membatasi penginstalan Marketplace ke aplikasi dalam daftar yang diizinkan, konsol Google Cloud akan membatasi kolom ini ke lima alamat email pengguna individual untuk pengembangan. Visibilitas grup hanya berlaku setelah administrator menambahkan aplikasi ke daftar yang diizinkan.
  6. 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.

  7. 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 Cloud CLI

Selain menggunakan Konsol Google Cloud, Anda dapat melihat dan memperbarui konfigurasi aplikasi Chat dari command line dengan Google Cloud CLI (gcloud CLI). Misalnya, Anda dapat mengonfigurasi aplikasi Chat dari skrip, atau menyimpan konfigurasinya dalam file yang Anda simpan bersama kode Anda.

Grup perintah gcloud beta workspace-add-ons chat-app-config memiliki perintah berikut:

  • describe: Menampilkan konfigurasi.
  • update: Mengonfigurasi aplikasi Chat untuk pertama kalinya, atau mengubah konfigurasinya.

Perintah ini menggunakan resource chatAppConfig di Google Workspace add-ons API.

Sebelum memulai

  1. Instal gcloud CLI. Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi terbaru dengan menjalankan gcloud components update.
  2. Login ke gcloud CLI dengan akun pengguna Anda. Perintah ini tidak mendukung akun layanan.

    gcloud auth login
  3. Tetapkan project Cloud aplikasi Chat Anda sebagai project default gcloud CLI. Gunakan project ID, karena perintah tidak menerima nomor project.

    gcloud config set project PROJECT_ID

    Atau, tambahkan flag --project ke setiap perintah.

  4. Aktifkan Google Workspace add-ons API di project Cloud:

    gcloud services enable gsuiteaddons.googleapis.com
  5. Pastikan Anda memiliki peran Identity and Access Management (IAM) berikut di project Cloud:

    • Developer Add-on Google Workspace (roles/gsuiteaddons.developer) untuk melihat dan memperbarui konfigurasi, atau Pembaca Add-on Google Workspace (roles/gsuiteaddons.reader) untuk hanya melihatnya. Peran ini mencakup izin yang tercantum dalam Prasyarat dan autentikasi.
    • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer). Gcloud CLI menggunakan project Cloud sebagai project kuota untuk permintaannya, yang memerlukan izin serviceusage.services.use.

    Peran Owner dan Editor mencakup semua izin ini. Peran Chat apps Owner dan Chat apps Viewer, yang memberikan akses ke halaman konfigurasi di Konsol Google Cloud, tidaklah cukup.

Melihat konfigurasi

Untuk melihat konfigurasi aplikasi Chat Anda, jalankan perintah describe:

gcloud beta workspace-add-ons chat-app-config describe

Outputnya mirip dengan hal berikut ini:

avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
  allowlistedTestingPrincipals:
  - user@example.com
  appCommands:
  - command: /help
    commandId: 1
    commandType: SLASH_COMMAND
    description: Show available commands
  connectionConfig:
    httpEndpointConfig:
      commonUrl: https://example.com/chat
  supportsMultiuserSpaces: true
  urlPatterns:
  - hostPattern: example.com
    pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE

Jika project Cloud belum memiliki aplikasi Chat, perintah akan berhasil dan hanya mencetak kolom name dari konfigurasi:

name: projects/123456789012/chatAppConfig

Untuk mengubah output, tambahkan salah satu flag berikut:

  • --format=json: Mencetak konfigurasi dalam format JSON.
  • --view=basic: Menghilangkan setelan fitur interaktif (interactiveFeatureConfig).
  • --format="value(displayName)": Hanya mencetak nama tampilan, atau baris kosong jika project Cloud belum memiliki aplikasi Chat. Aplikasi Chat yang dikonfigurasi selalu memiliki nama tampilan, sehingga Anda dapat menggunakan flag ini dalam skrip untuk memeriksa apakah aplikasi Chat ada.

Memperbarui konfigurasi

Untuk mengonfigurasi aplikasi Chat untuk pertama kalinya, atau untuk mengubah konfigurasinya, jalankan perintah update. Tentukan setelan dengan flag atau dalam file konfigurasi. Anda tidak dapat menggabungkan keduanya dalam satu perintah.

Saat pertama kali menjalankan perintah untuk project Cloud, Anda harus menentukan setidaknya nama tampilan dan deskripsi. Kecuali jika Anda menetapkan status ke nonaktif, aplikasi Chat akan aktif segera setelah perintah selesai. Orang yang Anda cantumkan sebagai penguji dapat menemukan dan menggunakannya.

Menggunakan flag

Contoh berikut mengonfigurasi aplikasi Chat yang menerima peristiwa di endpoint HTTP:

gcloud beta workspace-add-ons chat-app-config update \
    --display-name="Quickstart App" \
    --description="Quickstart app" \
    --avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
    --http-endpoint-url=HTTP_ENDPOINT_URL \
    --supports-multiuser-spaces \
    --add-allowlisted-testing-principals=USER_EMAIL \
    --error-logging-enabled

Ganti kode berikut:

  • HTTP_ENDPOINT_URL: URL HTTPS yang menerima objek peristiwa dari Chat.
  • USER_EMAIL: alamat email seseorang atau grup di organisasi Google Workspace Anda yang dapat menginstal dan menguji aplikasi Chat, seperti alamat email Anda sendiri.

Perintah ini mencetak konfigurasi yang diperbarui.

Tabel berikut mencantumkan flag untuk setelan di halaman Configuration Chat API di Konsol Google Cloud. Untuk mengetahui detail tentang setiap flag, lihat referensi perintah update.

Setelan di konsol Google Cloud Tanda
Nama aplikasi --display-name
URL avatar --avatar-uri dengan URL HTTPS gambar yang memenuhi persyaratan avatar, atau --clear-avatar-uri untuk menggunakan avatar default
Deskripsi --description
Status aplikasi --state=active atau --state=disabled
Sintaksis markup --markup-syntax=markdown atau --markup-syntax=chat
Bergabung ke ruang dan percakapan grup --supports-multiuser-spaces atau --no-supports-multiuser-spaces
Setelan koneksi Salah satu dari berikut ini:
  • URL endpoint HTTP: --http-endpoint-url
  • Apps Script: --apps-script-deployment-id
  • Cloud Pub/Sub: --pubsub-topic dengan topik di project Cloud yang sama, dalam format projects/PROJECT_ID/topics/TOPIC_ID
  • --dialogflow-edition=es Dialogflow, atau --dialogflow-edition=cx dengan --dialogflow-agent ditetapkan ke nama resource agen atau lingkungan, seperti projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID
Visibilitas --add-allowlisted-testing-principals, --remove-allowlisted-testing-principals, dan --clear-allowlisted-testing-principals
Mencatat error ke Logging --error-logging-enabled atau --no-error-logging-enabled

Perintah, pratinjau link, dan endpoint terpisah untuk setiap pemicu tidak memiliki flag. Untuk mengonfigurasinya, gunakan file konfigurasi.

Misalnya, untuk menonaktifkan aplikasi Chat tanpa mengubah setelan lainnya, jalankan perintah berikut. Untuk mengaktifkannya kembali, gunakan --state=active.

gcloud beta workspace-add-ons chat-app-config update --state=disabled

Menggunakan file konfigurasi

Untuk menyimpan konfigurasi dalam file, atau untuk mengonfigurasi setelan yang tidak memiliki flag, teruskan file YAML atau JSON ke perintah update. File ini menggunakan kolom resource chatAppConfig, yang merupakan kolom yang sama dengan yang dicetak oleh perintah describe.

  1. Buat file yang berisi setelan yang akan diperbarui. Misalnya, buat file bernama chat_app_config.yaml dengan konten berikut:

    displayName: Cymbal Assistant
    description: Helps manage tasks and schedules
    avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
    state: ACTIVE
    errorLoggingEnabled: true
    interactiveFeatureConfig:
      supportsMultiuserSpaces: true
      connectionConfig:
        httpEndpointConfig:
          commonUrl: https://example.com/chat
      appCommands:
      - commandId: 1
        commandType: SLASH_COMMAND
        command: /help
        description: Show available commands
      urlPatterns:
      - hostPattern: example.com
        pathPrefix: tasks/
      allowlistedTestingPrincipals:
      - USER_EMAIL
    

    Ganti USER_EMAIL dengan alamat email seseorang atau grup di organisasi Google Workspace Anda yang dapat menginstal dan menguji aplikasi Chat.

  2. Jalankan perintah update dengan flag --config-file:

    gcloud beta workspace-add-ons chat-app-config update \
        --config-file=chat_app_config.yaml

Untuk memulai dari konfigurasi aplikasi Chat saat ini, simpan output perintah describe ke file:

gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yaml

Kemudian, edit file, hapus kolom yang tidak ingin Anda ubah, dan teruskan file ke perintah update. Jika file berisi setelan yang tidak dapat diperbarui oleh perintah, perintah akan gagal. Untuk mengetahui detailnya, lihat Batasan.

Perintah update mengabaikan kolom name dalam file. File ini selalu mengupdate project Cloud yang Anda tetapkan di gcloud CLI, sehingga Anda dapat menggunakan file yang sama untuk mengonfigurasi aplikasi Chat di project Cloud lain.

Cara perintah menerapkan perubahan Anda

  • Hanya setelan yang Anda tentukan yang akan berubah. Dengan flag, perintah ini akan mengubah setelan untuk flag yang Anda teruskan. Dengan file konfigurasi, file ini mengubah kolom yang ada dalam file, sehingga file tidak perlu berisi seluruh konfigurasi. Setelan koneksi adalah pengecualian: jenis koneksi yang Anda tetapkan akan menggantikan jenis koneksi saat ini, dan edisi Dialogflow yang Anda tetapkan akan menggantikan seluruh konfigurasi Dialogflow.
  • Daftar diganti secara keseluruhan. Jika file berisi kolom appCommands, urlPatterns, atau allowlistedTestingPrincipals, daftar dalam file akan menggantikan daftar saat ini. Untuk menambahkan atau menghapus penguji satu per satu, gunakan flag --add-allowlisted-testing-principals dan --remove-allowlisted-testing-principals.
  • Nilai kosong akan menghapus setelan. Misalnya, file yang berisi urlPatterns: [] di bagian interactiveFeatureConfig akan menghapus semua pola URL pratinjau link.
  • Perintah yang gagal tidak akan mengubah apa pun. Jika nilai tidak valid, perintah akan mencetak error dan membiarkan konfigurasi seperti semula.
  • Kapasitas permintaan dibatasi. API membatasi jumlah permintaan baca dan permintaan update per menit, untuk setiap project Cloud dan untuk setiap organisasi. Setiap perintah update mengirimkan satu permintaan update. Jika Anda menambahkan atau menghapus penguji dengan flag, perintah tersebut juga akan mengirimkan permintaan baca. Untuk mengubah beberapa setelan, teruskan setelan tersebut dalam satu perintah atau satu file, bukan menjalankan perintah untuk setiap setelan.

Batasan

  • Perintah ini hanya mendukung aplikasi Chat yang dibuat sebagai add-on Google Workspace.
  • Perintah ini tidak mendukung akun layanan atau peniruan akun layanan. Anda harus login ke gcloud CLI dengan akun pengguna.
  • Project Cloud memiliki satu konfigurasi aplikasi Chat, dan perintah tidak dapat menghapusnya. Untuk menghentikan orang menggunakan aplikasi Chat, tetapkan statusnya ke nonaktif atau hapus project Cloud.
  • Update berlaku untuk aplikasi Chat yang aktif. Perintah tidak memiliki mode draf atau uji coba.
  • Saat aplikasi Chat dipublikasikan atau sedang ditinjau di Google Workspace Marketplace, perintah tidak dapat mengubah nama tampilan, avatar, deskripsi, perintah, atau pola URL pratinjau link-nya.
  • Perintah ini mendukung setelan di resource chatAppConfig. Untuk mengonfigurasi setelan yang tidak disertakan dalam resource, gunakan Konsol Google Cloud.

Memecahkan masalah

Jika perintah gagal, temukan teks dari pesan error di tabel berikut. Jika pesan dimulai dengan status seperti INVALID_ARGUMENT, Google Workspace add-ons API menolak permintaan, dan teks setelah status menjelaskan masalahnya.

Pesan error berisi Penyebab Solusi
Invalid choice: 'chat-app-config' atau Invalid choice: 'workspace-add-ons' Perintah tidak menyertakan beta, atau versi gcloud CLI Anda tidak menyertakan perintah tersebut. Mulai perintah dengan gcloud beta workspace-add-ons chat-app-config. Jika error berlanjut, update gcloud CLI ke versi terbaru.
PROJECT ID Project ditetapkan ke nomor project. Tetapkan project ke project ID.
Failed to parse value(s) in protobuf File konfigurasi berisi kolom yang tidak dikenali oleh gcloud CLI. Pesan error menyebutkan nama kolom. Bandingkan nama kolom dengan output perintah describe. Jika kolom tersebut baru, update gcloud CLI ke versi terbaru.
does not have permission to access projects instance API menolak permintaan. Teks setelah pesan ini memberikan alasannya. Contoh:
  • Akun Anda tidak memiliki peran IAM yang diperlukan. Jika teks berisi Caller does not have required permission to use project, peran Service Usage Consumer tidak ada.
  • Google Workspace add-ons API tidak diaktifkan di project Cloud.
  • Anda login dengan akun layanan.
Periksa persyaratan di bagian Sebelum memulai.
INVALID_ARGUMENT Nilai tidak valid. Misalnya, nama tampilan harus memiliki antara 3 dan 25 karakter, dan deskripsi antara 1 dan 40 karakter. Jika pesan berisi not found or deleted, project ID tidak benar. Perbaiki nilai yang dijelaskan dalam pesan error, lalu jalankan kembali perintah.
FAILED_PRECONDITION Aplikasi Chat tidak mengizinkan permintaan tersebut. Misalnya, add-on tersebut tidak dibuat sebagai add-on Google Workspace, atau dipublikasikan di Google Workspace Marketplace dan setelannya tidak dapat diubah. Ikuti petunjuk dalam pesan error. Untuk mengonfigurasi aplikasi Chat yang bukan add-on Google Workspace, gunakan Konsol Google Cloud atau konversikan.
RESOURCE_EXHAUSTED atau 429 API menerima terlalu banyak permintaan untuk project Cloud atau untuk organisasi Anda dalam waktu singkat. Tunggu sebentar, lalu jalankan kembali perintah tersebut.

Mengonfigurasi aplikasi Chat menggunakan Google Workspace Add-ons API

Daripada mengonfigurasi aplikasi Chat secara manual di Konsol Google Cloud, Anda dapat membaca dan memperbarui konfigurasi untuk aplikasi Chat yang dibuat sebagai add-on Google Workspace secara terprogram 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 mengupdate konfigurasi yang ada.

Prasyarat dan autentikasi

Sebelum memanggil GetChatAppConfig atau UpdateChatAppConfig, selesaikan prasyarat berikut:

  1. 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.
  2. 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.
  3. 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, chat.bots.update, dan chat.bots.get untuk memperbarui konfigurasi (UpdateChatAppConfig).
  4. Jika Anda menggunakan library klien, instal library klien Google Workspace Add-ons API versi terbaru untuk bahasa Anda. Untuk mengetahui daftar library klien, lihat referensi API add-on Google Workspace.

Memperbarui konfigurasi aplikasi Chat

Untuk mengonfigurasi aplikasi Chat untuk pertama kalinya atau mengupdate konfigurasi yang ada, kirim permintaan PATCH (UpdateChatAppConfig) ke resource singleton chatAppConfig 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 hal 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)

Batas penggunaan

Metode chatAppConfig memiliki kuota per project. Jika Anda melebihi kuota, permintaan akan gagal dengan kode status HTTP 429: Too many requests. Untuk batas kuota, lihat Batas penggunaan Google Workspace Add-ons API.

Mengatasi error

Jika permintaan chatAppConfig gagal, periksa kode status HTTP dan kolom message dalam respons error. Tabel berikut mencantumkan error umum, penyebabnya, dan cara mengatasinya.

Kode status HTTP Penyebab umum Resolusi
400: Bad Request (INVALID_ARGUMENT)
  • updateMask berisi kolom yang tidak ada atau tidak dapat diperbarui.
  • Nilai kolom tidak ada atau tidak valid. Misalnya, interactiveFeatureConfig tidak menyertakan connectionConfig.
Periksa kolom message untuk menemukan kolom yang tidak valid, dan perbaiki permintaan. Untuk kolom dan nilai yang didukung, lihat referensi projects.chatAppConfig.
400: Bad Request (FAILED_PRECONDITION)
  • Aplikasi Chat tidak dibuat sebagai add-on Google Workspace.
  • Kolom tidak dapat diubah karena aplikasi Chat dipublikasikan di Google Workspace Marketplace.
  • Nilai baru tidak kompatibel dengan konfigurasi aplikasi Chat yang ada.
  • Konversikan aplikasi Chat menjadi add-on Google Workspace, atau konfigurasikan di Konsol Google Cloud.
  • Ikuti petunjuk di kolom message untuk memperbarui listingan yang dipublikasikan.
  • Periksa kolom message untuk setelan yang bertentangan, dan perbarui kedua setelan dalam permintaan yang sama, atau ubah setelan yang ada terlebih dahulu.
403: Forbidden (PERMISSION_DENIED)
  • Pengguna yang diautentikasi tidak memiliki izin IAM yang diperlukan pada project Cloud.
  • Permintaan diautentikasi dengan akun layanan, bukan akun pengguna.
  • Beri pengguna izin yang tercantum dalam Prasyarat dan autentikasi.
  • Melakukan autentikasi sebagai pengguna manusia dengan cakupan https://www.googleapis.com/auth/cloud-platform.
404: Not Found (NOT_FOUND) Project Cloud dalam nama resource tidak ada, atau pengguna yang diautentikasi tidak dapat mengaksesnya. Pastikan nama resource menggunakan nomor project yang benar dalam format projects/PROJECT_NUMBER/chatAppConfig, dan pengguna memiliki akses ke project Cloud.
429: Too Many Requests (RESOURCE_EXHAUSTED) Kuota per project terlampaui. Tunggu dan coba lagi permintaan nanti. Untuk mengetahui batas, lihat Batas penggunaan.

Pertimbangan untuk add-on Google Workspace yang 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, dengan gcloud CLI, atau menggunakan resource chatAppConfig di Google Workspace add-ons API.

Memberi orang lain izin untuk mengonfigurasi Chat API

Anda dapat memberi pengguna tertentu akses ke halaman konfigurasi aplikasi Chat dengan memberi mereka peran Identity Access Management (IAM) Google Cloud 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 Fitur interaktif, aktifkan Aktifkan fitur interaktif.

  3. Buat aplikasi Chat ini sebagai add-on Google Workspace. Dialog akan terbuka dan meminta Anda 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. Konfigurasi Commands, perintah pemicu, 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.