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 pesan dan dialog kartu.

Lihat cara kerja aplikasi Chat:

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.
• Merespons perintah garis miring dengan mengirim 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 menunjukkan 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 mem-build 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 dengan formulir kontak.
   • Merespons perintah garis miring /about dengan pesan teks yang memiliki tombol Tambahkan kontak yang dapat diklik pengguna untuk membuka dialog dengan 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 akan 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 menu > IAM & Admin > Create a Project.

   Buka Membuat 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 ID 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.
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 sehingga pengguna dapat memberikan otorisasi ke 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 dengan informasi yang sebenarnya.

1. Di konsol Google Cloud, buka Menu menu > > Branding.

   Buka Branding

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

   1. Di bagian Informasi Aplikasi, di Nama aplikasi, ketik Contact Manager.
   2. Di Email dukungan pengguna, 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 Eksternal.
   5. Klik Berikutnya.
   6. Di bagian Informasi Kontak, masukkan Alamat email tempat Anda dapat diberi tahu 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 setuju dengan 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 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 adalah ringkasan setiap file:

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 more_vert > 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 Mengelola kontak di Google Chat.
   Membuka project
2. Klik info_outline Ringkasan.
3. Di halaman ringkasan, klik Buat salinan.

4. Beri nama salinan project Apps Script Anda:

   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 diterapkan, 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 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 content_copy 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 menu > Produk lainnya > Google Workspace > Product Library > Google Chat API > Manage > Configuration.

   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 Visibilitas, centang kotak Buat 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 add 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.

1. Di pesan langsung baru dengan aplikasi Chat, ketikkan /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 Birthdate, pilih tanggal.
   3. Di bagian Jenis kontak, pilih tombol pilihan Kantor 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 untuk membuka dialog dengan 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.

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

   Buka Resource Manager

2. Dalam 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

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