Mengumpulkan dan mengelola kontak di Google Chat

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

Lihat cara kerja aplikasi Chat:

• 

  Gambar 1. Aplikasi Chat merespons perintah garis miring /about dengan pesan teks dan tombol yang membuka formulir kontak.

• 
  Gambar 2. Aplikasi Chat membuka dialog tempat pengguna dapat memasukkan informasi tentang kontak.
• 
  Gambar 3. Aplikasi Chat menampilkan dialog konfirmasi sehingga pengguna dapat meninjau dan mengonfirmasi informasi sebelum mengirimkannya.
• 
  Gambar 4. Setelah pengguna mengirimkan formulir, aplikasi Chat akan mengirim pesan teks pribadi untuk mengonfirmasi pengiriman.
• 
  Gambar 5. Aplikasi Chat juga meminta pengguna untuk menambahkan kontak dari kartu dalam pesan.

Prasyarat

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

Tujuan

• Buat desain dan build antarmuka pengguna (UI) sebagai objek card, dan tampilkan UI dalam pesan dan dialog.
• Menerima dan memproses informasi yang dikirimkan pengguna menggunakan widget input formulir.
• Respons perintah garis miring dengan mengirimkan pesan yang berisi teks, kartu, dan widget aksesori.

Arsitektur

Aplikasi Chat dibuat di Google Apps Script dan menggunakan peristiwa interaksi untuk memproses dan merespons pengguna Chat.

Berikut ini adalah 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 akan merespons pengguna dengan cara berikut:

   • Merespons @sebutan dan pesan langsung dengan pesan kartu yang berisi formulir kontak.
   • Merespons perintah garis miring /addContact dengan membuka dialog berisi formulir kontak.
   • Merespons perintah garis miring /about dengan pesan teks yang memiliki tombol Add a contact yang dapat diklik pengguna untuk membuka dialog berisi formulir kontak.

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

   • Nama depan dan 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 dimasukkan.

4. Aplikasi Google Chat menangani peristiwa interaksi CARD_CLICKED untuk memproses nilai yang dimasukkan pengguna, dan menampilkan nilai dalam kartu konfirmasi.

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

6. Aplikasi Google Chat mengirim pesan teks pribadi yang mengonfirmasi pengiriman.

Menyiapkan lingkungan

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

Membuat project Google Cloud

Konsol Google Cloud

1. Di konsol Google Cloud, buka Menu > IAM & Admin > Create a Project.

   Buka bagian Create a Project

2. Di kolom Project Name, masukkan nama deskriptif untuk project Anda.

   Opsional: Untuk mengedit Project ID, klik Edit. Project ID tidak dapat diubah setelah project dibuat. Jadi, pilih yang sesuai dengan kebutuhan Anda sepanjang waktu project tersebut.

3. Di kolom Location, klik Browse untuk menampilkan lokasi potensial untuk project Anda. Kemudian, klik Select.
   Perhatian: Tidak dapat menemukan organisasi Google Workspace Anda?
   Artinya, Anda tidak login ke akun Google Workspace. Beberapa fitur yang dijelaskan dalam dokumentasi developer Google Workspace hanya tersedia untuk project yang terkait dengan organisasi.
4. Klik Buat. Konsol Google Cloud akan membuka halaman Dasbor dan project Anda akan dibuat dalam beberapa menit.

gcloud CLI

Di salah satu lingkungan pengembangan berikut, akses Google Cloud CLI (gcloud):

• Cloud Shell: Untuk menggunakan terminal online dengan gcloud CLI yang sudah disiapkan, aktifkan Cloud Shell.
  Aktifkan Cloud Shell
• Shell Lokal: Untuk menggunakan lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI.
  Untuk membuat project Cloud, gunakan perintah gcloud projects create:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan menetapkan ID untuk project yang ingin Anda buat.

Menyiapkan autentikasi dan otorisasi

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

Dalam tutorial ini, Anda 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 apa pun dengan informasi sungguhan.

1. Di konsol Google Cloud, buka Menu > APIs & Services > OAuth consent screen.

   Buka layar izin OAuth

2. Di bagian Jenis pengguna, pilih Internal, lalu klik Buat.

3. Di App name, ketik Contact Manager.

4. Di Email dukungan pengguna, pilih alamat email Anda atau grup Google yang sesuai.

5. Di bagian Informasi kontak developer, masukkan alamat email Anda.

6. Klik Simpan dan Lanjutkan.

7. Di halaman Cakupan, klik Simpan dan Lanjutkan. (Aplikasi Chat tidak memerlukan cakupan OAuth apa pun.)

8. Tinjau ringkasan, lalu klik Kembali ke Dasbor.

Membuat dan men-deploy aplikasi Chat

Di bagian berikut, Anda akan menyalin dan memperbarui seluruh project Apps Script yang berisi semua kode aplikasi yang diperlukan untuk aplikasi Chat, sehingga Anda tidak perlu menyalin dan menempelkan setiap file.

Secara opsional, Anda dapat melihat seluruh project di GitHub.

Lihat di GitHub

Berikut ringkasan setiap filenya:

main.gs

Menangani semua logika aplikasi, termasuk peristiwa interaksi tentang kapan pengguna mengirim pesan ke aplikasi Chat, mengklik tombol dari pesan aplikasi Chat, atau membuka dan menutup dialog.

Lihat kode main.gs

apps-script/contact-form-app/main.gs

Lihat di GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * 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 interaction event in Google Chat.
 *
 * @param {Object} event the MESSAGE interaction event from Chat API.
 * @return {Object} message response that opens a dialog or sends private
 *                          message with text and card.
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1:
        // If the slash command is "/about", responds with a text message and button
        // that opens a dialog.
        return {
          text: "Manage your personal and business contacts 📇. To add a " +
                  "contact, use the slash command `/addContact`.",
          accessoryWidgets: [{
            buttonList: { buttons: [{
              text: "Add Contact",
              onClick: { action: {
                function: "openInitialDialog",
                interaction: "OPEN_DIALOG"
              }}
            }]}
          }]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openInitialDialog();
    }
  }

  // If user sends the Chat app a message without a slash command, the app responds
  // privately with a text and card to add a contact.
  return {
    privateMessageViewer: event.user,
    text: "To add a contact, try `/addContact` or complete the form below:",
    cardsV2: [{
      cardId: "addContactForm",
      card: {
        header: { title: "Add a contact" },
        sections:[{ widgets: CONTACT_FORM_WIDGETS.concat([{
          buttonList: { buttons: [{
            text: "Review and submit",
            onClick: { action: { function : "openConfirmation" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @return {Object} message responses specific to the dialog handling.
 */
function onCardClick(event) {
  // Initial dialog form page
  if (event.common.invokedFunction === "openInitialDialog") {
    return openInitialDialog();
  // Confirmation dialog form page
  } else if (event.common.invokedFunction === "openConfirmation") {
    return openConfirmation(event);
  // Submission dialog form page
  } else if (event.common.invokedFunction === "submitForm") {
    return submitForm(event);
  }
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openInitialDialog() {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { dialog: { body: { sections: [{
      header: "Add new contact",
      widgets: CONTACT_FORM_WIDGETS.concat([{
        buttonList: { buttons: [{
          text: "Review and submit",
          onClick: { action: { function: "openConfirmation" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns the second step as a dialog or card message that lets users confirm details.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} returns a dialog or private card message.
 */
function openConfirmation(event) {
  const name = fetchFormValue(event, "contactName") ?? "";
  const birthdate = fetchFormValue(event, "contactBirthdate") ?? "";
  const type = fetchFormValue(event, "contactType") ?? "";
  const cardConfirmation = {
    header: "Your contact",
    widgets: [{
      textParagraph: { text: "Confirm contact information and submit:" }}, {
      textParagraph: { text: "<b>Name:</b> " + name }}, {
      textParagraph: {
        text: "<b>Birthday:</b> " + convertMillisToDateString(birthdate)
      }}, {
      textParagraph: { text: "<b>Type:</b> " + type }}, {
      buttonList: { buttons: [{
        text: "Submit",
        onClick: { action: {
          function: "submitForm",
          parameters: [{
            key: "contactName", value: name }, {
            key: "contactBirthdate", value: birthdate }, {
            key: "contactType", value: type
          }]
        }}
      }]}
    }]
  };

  // Returns a dialog with contact information that the user input.
  if (event.isDialogEvent) {
    return { action_response: {
      type: "DIALOG",
      dialogAction: { dialog: { body: { sections: [ cardConfirmation ]}}}
    }};
  }

  // Updates existing card message with contact information that the user input.
  return {
    actionResponse: { type: "UPDATE_MESSAGE" },
    privateMessageViewer: event.user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Validates and submits information from a dialog or card message
  * and notifies status.
  *
  * @param {Object} event the interactive event with parameters.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(event) {
  const contactName = event.common.parameters["contactName"];
  // Checks to make sure the user entered a contact name.
  // If no name value detected, returns an error message.
  if (!contactName) {
    const errorMessage = "Don't forget to name your new contact!";
    if (event.dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: event.user,
        text: errorMessage
      };
    }
  }

  // The Chat app indicates that it received form data from the dialog or card.
  // Sends private text message that confirms submission.
  const confirmationMessage = "✅ " + contactName + " has been added to your contacts.";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + contactName
        }}
      }
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: event.user,
      text: confirmationMessage
    };
  }
}

/**
 * Extracts form input value for a given widget.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @param {String} widgetName a unique ID for the widget, specified in the widget's name field.
 * @returns the value inputted by the user, null if no value can be found.
 */
function fetchFormValue(event, widgetName) {
  const formItem = event.common.formInputs[widgetName][""];
  // For widgets that receive StringInputs data, the value input by the user.
  if (formItem.hasOwnProperty("stringInputs")) {
    const stringInput = event.common.formInputs[widgetName][""].stringInputs.value[0];
    if (stringInput != null) {
      return stringInput;
    }
  // For widgets that receive dateInput data, the value input by the user.
  } else if (formItem.hasOwnProperty("dateInput")) {
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;
     if (dateInput != null) {
       return dateInput;
     }
  }

  return null;
}

/**
 * Converts date in milliseconds since epoch to user-friendly string.
 *
 * @param {Object} millis the milliseconds since epoch time.
 * @return {string} Display-friend date (English US).
 */
function convertMillisToDateString(millis) {
  const date = new Date(millis);
  const options = { year: 'numeric', month: 'long', day: 'numeric' };
  return date.toLocaleDateString('en-US', options);
}

contactForm.gs

Berisi widget yang menerima data formulir dari pengguna. Widget input formulir ini ditampilkan dalam kartu yang muncul dalam pesan dan dialog.

Lihat kode contactForm.gs

apps-script/contact-form-app/contactForm.gs

Lihat di GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * 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.
 */

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_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
        }
      ]
    }
  }
];

appsscript.json

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

Lihat kode appsscript.json

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

Lihat di GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

Menemukan nomor dan ID project Cloud Anda

1. Di konsol Google Cloud, buka project Cloud Anda.

   Buka konsol Google Cloud

2. Klik Settings and Utilities > Project settings.

3. Catat nilai di kolom Nomor project dan Project ID. Anda akan menggunakannya di bagian berikut.

Membuat project Apps Script

Untuk membuat project Apps Script dan menghubungkannya dengan project Cloud Anda:

1. Klik tombol berikut untuk membuka project Apps Script Kelola kontak di Google Chat.
   Membuka project
2. Klik Ringkasan.
3. Di halaman ringkasan, klik Buat salinan.

4. Beri nama salinan project Apps Script:

   1. Klik Salinan Kelola kontak di Google Chat.

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

   3. Klik Ganti nama.

Menetapkan project Cloud project Apps Script

1. Di project Apps Script, klik Project Settings.
2. Pada Google Cloud Platform (GCP) Project, klik Change project.
3. Di GCP project number, tempel nomor project project Cloud Anda.
4. Klik Set project. Project Cloud dan project Apps Script kini terhubung.

Membuat deployment Apps Script

Setelah semua kode siap, 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 samping Select type, klik jenis deployment , lalu pilih Add-on.

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

5. Klik Deploy. Apps Script melaporkan deployment yang berhasil dan memberikan ID deployment.

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

Mengonfigurasi aplikasi Chat di Konsol Google Cloud

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

1. Di konsol Google Cloud, klik Menu > Produk lainnya > Google Workspace > Library Produk > Google Chat API > Kelola > Konfigurasi.

   Buka konfigurasi Chat API

2. Di App name, ketik Contact Manager.

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

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

5. Klik tombol Aktifkan Fitur interaktif ke posisi aktif.

6. Di bagian Functionality, centang kotak Receive 1:1 messages dan 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 Slash commands, siapkan perintah garis miring /about dan /addContact:

   1. Klik Tambahkan perintah garis miring untuk menyiapkan perintah garis miring pertama.
   2. Di Name, ketik /about.
   3. Di Command ID, ketik 1.
   4. Di Deskripsi, ketik Learn how to use this Chat app to manage your contacts.
   5. Pilih Opens a dialog.
   6. Klik Selesai.
   7. Klik Tambahkan perintah garis miring untuk menyiapkan perintah garis miring lain.
   8. Di Nama, ketik /addContact
   9. Di Command ID, ketik 2.
   10. Di Deskripsi, ketik Submit information about a contact.
   11. Pilih Opens a dialog.
   12. Klik Selesai.

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

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

12. Klik Simpan. Pesan konfigurasi tersimpan akan muncul.

Aplikasi Chat siap diinstal dan diuji di Chat.

Menguji aplikasi Chat

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

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

   Buka Google Chat

2. Klik Chat 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.

   Catatan: Jika Anda tidak melihat aplikasi Chat dalam daftar hasil, pastikan Anda telah menyertakan akun Google Workspace di setelan Visibilitas di halaman Konfigurasi Chat API di konsol Google Cloud.

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 Kerja atau Pribadi.

3. Klik Review and submit.

4. Pada dialog konfirmasi, tinjau informasi yang Anda kirimkan, lalu klik Kirim. Aplikasi Chat membalas dengan pesan teks yang bertuliskan ✅ 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 ini untuk membuka dialog berisi formulir kontak.
   • Kirim pesan langsung ke aplikasi Chat tanpa perintah garis miring, seperti Hello. Aplikasi Chat akan 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.

Perhatian: Menghapus project memiliki efek berikut:

• Semua hal dalam project akan dihapus. Jika menggunakan project yang sudah ada untuk tutorial ini, saat menghapusnya, Anda juga akan menghapus pekerjaan lain yang telah dilakukan dalam project tersebut.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin telah membuat project ID kustom yang masih ingin Anda gunakan pada masa mendatang. Untuk mempertahankan URL yang menggunakan project ID tersebut, seperti URL di appspot.com, hapus resource yang dipilih di dalam project, alih-alih menghapus seluruh project.

Jika Anda berencana mempelajari beberapa tutorial dan panduan memulai, menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

1. Di Konsol Google Cloud, buka halaman Manage resources. Klik Menu > IAM & Admin > Manage Resources.

   Buka Resource Manager

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

Topik terkait

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