Mengumpulkan dan mengelola kontak di Google Chat

Tutorial ini menunjukkan cara membuat aplikasi Google Chat yang membantu pengguna Google Chat mengelola kontak pribadi dan bisnis mereka. Untuk mengumpulkan informasi, aplikasi Chat akan meminta pengguna untuk melengkapi formulir kontak dalam pesan kartu dan dialog.

Lihat cara kerja aplikasi Chat:

Prasyarat

• Akun Google Workspace Business atau Enterprise dengan akses ke Google Chat.
• Buat project Google Cloud.

Tujuan

• Mendesain dan membuat antarmuka pengguna (UI) sebagai objek card, dan menampilkan UI dalam pesan dan dialog.
• Menerima dan memproses informasi yang dikirimkan pengguna menggunakan widget input formulir.
• Merespons perintah dengan pesan yang berisi teks, kartu, dan widget aksesori.

Arsitektur

Aplikasi Chat dibuat di Google Apps Script (sebagai add-on Google Workspace yang memperluas Google Chat) dan merespons interaksi pengguna (onMessage, onAppCommand, dan klik tombol yang memanggil openInitialDialog, openConfirmationDialog, dan submitForm) untuk memproses dan merespons pengguna Chat.

Berikut cara pengguna biasanya berinteraksi dengan aplikasi Chat:

1. Pengguna membuka pesan langsung dengan aplikasi Chat, atau menambahkan aplikasi Chat ke ruang yang ada.

2. Aplikasi Chat meminta pengguna untuk menambahkan kontak dengan membuat dan menampilkan formulir kontak sebagai objek card. Untuk menampilkan formulir kontak, aplikasi Chat merespons pengguna dengan cara berikut:

   • Merespons @sebutan dan pesan langsung (onMessage) dengan pesan kartu yang berisi formulir kontak.
   • Merespons perintah garis miring /addContact (onAppCommand) dengan membuka dialog yang berisi formulir kontak.
   • Merespons perintah garis miring /about (onAppCommand) dengan pesan teks yang memiliki tombol Tambahkan kontak yang dapat diklik pengguna untuk memanggil openInitialDialog dan membuka dialog dengan formulir kontak.

3. Saat melihat formulir kontak, pengguna memasukkan informasi kontak ke dalam kolom dan widget berikut:

   • Nama depan dan nama belakang: widget textInput yang menerima string.
   • Tanggal lahir: widget dateTimePicker yang hanya menerima tanggal.
   • Jenis kontak: widget selectionInput tombol pilihan yang memungkinkan pengguna memilih dan mengirimkan satu nilai string (Personal atau Work).
   • Tombol Tinjau dan kirim: array buttonList dengan widget button yang diklik pengguna untuk mengirimkan nilai yang mereka masukkan.

4. Aplikasi Google Chat memanggil openConfirmationDialog untuk memproses nilai yang dimasukkan pengguna, dan menampilkan nilai tersebut dalam kartu konfirmasi.

5. Pengguna meninjau kartu konfirmasi dan mengklik tombol Kirim untuk memanggil submitForm dan menyelesaikan informasi kontak.

6. Aplikasi Google Chat akan mengirimkan pesan teks pribadi yang mengonfirmasi pengiriman.

Menyiapkan lingkungan

Bagian ini menunjukkan cara mengonfigurasi project Google Cloud untuk aplikasi Chat.

Buka project Cloud Anda di Konsol API Google

Jika belum terbuka, buka project Cloud yang ingin Anda gunakan untuk contoh ini:

1. Di Konsol API Google, buka halaman Pilih project.

   Pilih project Cloud

2. Pilih project Google Cloud yang ingin Anda gunakan. Atau, klik Buat project dan ikuti petunjuk di layar. Jika membuat project Google Cloud, Anda mungkin perlu mengaktifkan penagihan untuk project tersebut.

Menyiapkan autentikasi dan otorisasi

Aplikasi Google Chat mengharuskan Anda mengonfigurasi layar izin OAuth agar pengguna dapat memberikan otorisasi ke aplikasi Anda di aplikasi Google Workspace, termasuk Google Chat.

Dalam tutorial ini, Anda akan men-deploy aplikasi Chat yang hanya untuk pengujian dan penggunaan internal, jadi Anda dapat menggunakan informasi placeholder untuk layar izin. Sebelum memublikasikan aplikasi Chat, ganti informasi placeholder dengan informasi yang sebenarnya.

1. Di Konsol API Google, buka Menu menu > Google Auth platform > Branding.

   Buka Branding

2. Jika telah mengonfigurasi platform Google Auth, Anda dapat mengonfigurasi setelan Layar Izin OAuth berikut di Branding, Audiens, dan Akses Data. Jika Anda melihat pesan yang menyatakan Google Auth platform not configured yet, klik Get Started:

   1. Di bagian Informasi Aplikasi, di Nama aplikasi, ketik Contact Manager.
   2. Di User support email, pilih alamat email Anda atau grup Google yang sesuai.
   3. Klik Berikutnya.
   4. Di bagian Audiens, pilih Internal. Jika Anda tidak dapat memilih Internal, pilih External.
   5. Klik Berikutnya.
   6. Di bagian Informasi Kontak, masukkan Alamat email tempat Anda dapat menerima notifikasi tentang perubahan apa pun pada project Anda.
   7. Klik Berikutnya.
   8. Di bagian Selesai, tinjau Kebijakan Data Pengguna Layanan Google API dan jika Anda setuju, pilih Saya menyetujui Layanan Google API: Kebijakan Data Pengguna.
   9. Klik Lanjutkan.
   10. Klik Buat.
   11. Jika Anda memilih Eksternal untuk jenis pengguna, tambahkan pengguna pengujian:
       1. Klik Audiens.
       2. Di bagian Pengguna pengujian, klik Tambahkan pengguna.
       3. Masukkan alamat email Anda dan pengguna pengujian resmi lainnya, lalu klik Simpan.

Membuat dan men-deploy aplikasi Chat

Di bagian berikut, Anda akan membuat dan mengupdate project Apps Script dengan kode aplikasi (Code.gs dan appsscript.json) untuk aplikasi Chat Anda.

Secara opsional, Anda dapat melihat seluruh project di GitHub.

Lihat di GitHub

Berikut ringkasan setiap file:

Code.gs

Menangani semua logika aplikasi, termasuk interaksi pengguna (onMessage, onAppCommand, openInitialDialog, openConfirmationDialog, dan submitForm) serta widget input formulir yang ditampilkan dalam kartu di pesan dan dialog.

Lihat kode Code.gs

apps-script/chat/contact-form-app/Code.gs

Lihat di GitHub

/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [
      { buttonList: { buttons: [{
        text: "ADD CONTACT",
        onClick: { action: {
          function: "openInitialDialog",
          interaction: "OPEN_DIALOG"
        }}
      }]}}
    ]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    { dateTimePicker: {
      name: "contactBirthdate",
      label: "Birthdate",
      type: "DATE_ONLY"
    }},
    { selectionInput: {
      name: "contactType",
      label: "Contact type",
      type: "RADIO_BUTTON",
      items: [
        { text: "Work", value: "Work", selected: false },
        { text: "Personal", value: "Personal", selected: false }
      ]
    }},
    { buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  const birthdate = event.commonEventObject.formInputs["contactBirthdate"].dateInput.msSinceEpoch;
  const type = event.commonEventObject.formInputs["contactType"].stringInputs.value[0];
  // Display the input values for confirmation
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textParagraph: { text: "Confirm contact information and submit:" }},
    { textParagraph: { text: "<b>Name:</b> " + name }},
    { textParagraph: { text: "<b>Birthday:</b> " + new Date(birthdate) }},
    { textParagraph: { text: "<b>Type:</b> " + type }},
    { buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [
          { key: "contactName", value: name },
          { key: "contactBirthdate", value: birthdate },
          { key: "contactType", value: type }
        ]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification or message.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
  }}}}};
}

appsscript.json

Manifes Apps Script yang menentukan dan mengonfigurasi project Apps Script untuk aplikasi Chat.

Lihat kode appsscript.json

apps-script/chat/contact-form-app/appsscript.json

Lihat di GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Contact Form app",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/contact-icon.png"
    },
    "chat": {}
  }
}

Buat project Apps Script

Untuk membuat project Apps Script dari file Code.gs dan appsscript.json:

1. Buka Google Apps Script, lalu klik Project baru.

2. Beri nama project Apps Script Anda:

   1. Klik Project tanpa judul.

   2. Di Project title, ketik Contact Manager - Google Chat app.

   3. Klik Ganti nama.

3. Ganti konten Code.gs dengan kode contoh Code.gs di atas.

4. Klik Setelan Project , lalu pilih Tampilkan file manifes "appsscript.json" di editor.

5. Kembali ke Editor dan ganti konten appsscript.json dengan kode manifes appsscript.json di atas, lalu simpan project Anda.

Pada masa mendatang, jika Anda ingin menggunakan Google API tertentu atau memublikasikan aplikasi, Anda harus mengaitkan project Cloud dengan project Apps Script. Untuk panduan ini, Anda tidak perlu melakukannya. Untuk mempelajari lebih lanjut, lihat panduan project Google Cloud.

Membuat deployment Apps Script

Setelah semua kode tersedia, deploy project Apps Script. Anda menggunakan ID deployment saat mengonfigurasi aplikasi Chat di Google Cloud.

1. Di Apps Script, buka project aplikasi Chat.

   Buka Apps Script

2. Klik Deploy > New deployment.

3. Jika Add-on belum dipilih, di sebelah Pilih jenis, klik jenis deployment , lalu pilih Add-on.

4. Di Deskripsi, masukkan deskripsi untuk versi ini, seperti Test of Contact Manager.

5. Klik Deploy. Apps Script melaporkan keberhasilan deployment dan memberikan ID deployment.

6. Klik content_copy Salin untuk menyalin ID deployment, lalu klik Selesai.

Mengonfigurasi aplikasi Chat di Konsol API Google

Bagian ini menunjukkan cara mengonfigurasi Google Chat API di Konsol API Google dengan informasi tentang aplikasi Chat Anda, termasuk ID deployment yang baru saja Anda buat dari project Apps Script.

1. Di Konsol API Google, klik Menu menu > APIs & Services > Enabled APIs & Services > Google Chat API > Configuration.

   Buka konfigurasi Chat API

2. Di Nama aplikasi, ketik Contact Manager.

3. Di Avatar URL, ketik https://developers.google.com/chat/images/contact-icon.png.

4. Di Description, ketik Manage your personal and business contacts.

5. Klik tombol Aktifkan fitur Interaktif ke posisi aktif.

6. Di bagian Functionality, pilih Join spaces and group conversations.

7. Di bagian Connection settings, pilih Apps Script.

8. Di Deployment ID, tempelkan ID Deployment Apps Script yang Anda salin di bagian sebelumnya saat membuat deployment Apps Script.

9. Di bagian Pemicu, konfigurasikan fungsi yang merespons interaksi pengguna:

   • Untuk pemicu Message, masukkan onMessage.
   • Untuk pemicu Perintah aplikasi, masukkan onAppCommand.

10. Di bagian Commands, siapkan perintah garis miring /about dan /addContact:

    1. Klik Tambahkan perintah untuk menyiapkan perintah garis miring pertama.
    2. Di Command ID, ketik 1.
    3. Di Description, ketik Learn how to use this Chat app to manage your contacts.
    4. Di bagian Command type, pilih Slash command.
    5. Di Slash command name, ketik /about.
    6. Klik Selesai.
    7. Klik Tambahkan perintah untuk menyiapkan perintah garis miring lainnya.
    8. Di Command ID, ketik 2.
    9. Di Description, ketik Submit information about a contact.
    10. Di bagian Command type, pilih Slash command.
    11. Di Slash command name, ketik /addContact.
    12. Pilih Opens a dialog.
    13. Klik Selesai.

11. Di bagian Visibilitas, centang kotak Jadikan aplikasi Chat ini tersedia untuk orang dan grup tertentu di YOUR DOMAIN dan masukkan alamat email Anda.

12. Di bagian Logs, pilih Log errors to Logging.

13. Klik Simpan. Pesan konfigurasi disimpan akan muncul.

Aplikasi Chat siap diinstal dan diuji di Chat.

Menguji aplikasi Chat

Untuk menguji aplikasi Chat Anda, buka ruang pesan langsung dengan aplikasi Chat dan kirim pesan:

1. Buka Google Chat menggunakan akun Google Workspace yang Anda berikan saat menambahkan diri Anda sebagai penguji tepercaya.

   Buka Google Chat.

2. Klik add Percakapan baru.
3. Di kolom Tambahkan 1 orang atau lebih, ketik nama aplikasi Chat Anda.

4. Pilih aplikasi Chat Anda dari hasil. Pesan langsung akan terbuka.

1. Di pesan langsung baru dengan aplikasi Chat, ketik /addContact, lalu tekan enter.

2. Pada dialog yang terbuka, masukkan informasi kontak:

   1. Di kolom teks Nama depan dan nama belakang, masukkan nama.
   2. Di pemilih tanggal Tanggal lahir, pilih tanggal.
   3. Di bagian Jenis kontak, pilih tombol pilihan Kantor atau Pribadi.

3. Klik Tinjau dan kirim.

4. Pada dialog konfirmasi, tinjau informasi yang Anda kirimkan, lalu klik Kirim. Aplikasi Chat membalas dengan pesan teks yang mengatakan ✅ CONTACT NAME has been added to your contacts..

5. Secara opsional, Anda juga dapat menguji dan mengirimkan formulir kontak dengan cara berikut:

   • Gunakan perintah garis miring /about. Aplikasi chat membalas dengan pesan teks dan tombol widget aksesori yang bertuliskan Add a contact. Anda dapat mengklik tombol untuk membuka dialog dengan formulir kontak.
   • Kirim pesan langsung ke aplikasi Chat tanpa perintah garis miring, seperti Hello. Aplikasi Chat membalas dengan teks dan kartu yang berisi formulir kontak.

Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, sebaiknya hapus project Cloud tersebut.

1. Di Konsol API Google, buka halaman Kelola resource. Klik Menu menu > IAM & Admin > Kelola Resource.

   Buka Resource Manager

2. Pada daftar project, pilih project yang ingin Anda hapus, lalu klik Hapus delete.
3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

Topik terkait

• Menanggapi perintah
• Mengumpulkan dan memproses informasi dari pengguna Google Chat
• Membuka dialog interaktif
• Menjelajahi contoh aplikasi Google Chat lainnya