Pergi berlibur dengan aplikasi Google Chat

1. Pengantar

Aplikasi Google Chat menghadirkan layanan dan resource langsung ke Chat tempat pengguna mendapatkan informasi dan dapat mengambil tindakan tanpa keluar dari percakapan.

Di codelab ini, Anda mempelajari cara membuat aplikasi Chat—"Bot Kehadiran"—yang menyetel penjawab saat libur di Gmail dan menjadwalkan rapat di Google Kalender. Dengan membangun Bot Kehadiran di Google Apps Script, Anda dapat dengan mudah mengakses layanan Google lainnya seperti Drive, Gmail, Kalender, Dokumen, Spreadsheet, dan banyak lagi.

Yang akan Anda pelajari

• Cara menambahkan pengendali dalam peristiwa yang dimunculkan di Chat
• Cara mengurai objek peristiwa yang dikirim dari Chat
• Cara menanggapi Chat dengan respons berformat kartu
• Cara menentukan dan bereaksi terhadap tindakan khusus untuk klik tombol di kartu

Yang Anda butuhkan

• Akses ke internet dan browser web.
• Akun Google Workspace dengan akses ke Google Chat.
• Keterampilan JavaScript dasar—Google Apps Script hanya mendukung JavaScript.

Peringatan: Anda harus menggunakan akun Google Workspace untuk menyelesaikan codelab ini. Jika Anda menggunakan akun @gmail.com, akan muncul error saat akan mengaktifkan API.

2. Mendapatkan kode contoh

Anda dapat mendownload file ZIP atau meng-clone repositori GitHub untuk melihat kode untuk setiap langkah dalam contoh ini.

Folder step-NN berisi status akhir yang diinginkan dari setiap langkah codelab ini. Folder tersebut disediakan sebagai referensi

Download kodenya

Untuk mendownload kode untuk codelab ini, klik tombol berikut:

Download kode sumber

Ekstrak file ZIP yang didownload. Tindakan ini akan mengeluarkan folder root (hangouts-chat-apps-script-codelab), yang berisi satu folder untuk setiap langkah codelab ini.

Meng-clone repositori GitHub

Untuk meng-clone repositori GitHub untuk codelab ini, jalankan perintah berikut:

git clone https://github.com/googleworkspace/hangouts-chat-apps-script-codelab

3. Membuat pengendali untuk peristiwa Google Chat

Membuat project Apps Script

Untuk membuat project Apps Script, lakukan langkah-langkah berikut:

1. Buka script.new.
2. Klik Project tanpa judul.
3. Ganti nama skrip Bot Kehadiran lalu klik Ganti Nama.

Peristiwa di Google Chat

Sebagian besar interaksi Apps Script dengan Chat didorong oleh peristiwa. Interaksi antara pengguna, aplikasi Chat, dan Chat biasanya mengikuti urutan berikut:

1. Pengguna memulai tindakan, seperti menambahkan aplikasi Chat ke suatu ruang, memulai pesan langsung (DM) dengan aplikasi Chat, atau menghapus aplikasi Chat dari ruang.
2. Tindakan tersebut memunculkan peristiwa yang ditujukan untuk aplikasi Chat di Chat.
3. Chat memanggil pengendali peristiwa terkait yang ditentukan dalam skrip aplikasi Chat.

Chat memunculkan 4 peristiwa yang dapat direspons oleh aplikasi Anda:

• ADDED_TO_SPACE: Peristiwa ini terjadi saat pengguna manusia menambahkan aplikasi Chat ke ruang atau menambahkan pesan langsung (DM). Di Apps Script, Anda menentukan fungsi onAddToSpace() untuk menangani peristiwa ini.
• REMOVED_FROM_SPACE: Peristiwa ini terjadi saat pengguna menghapus aplikasi Chat dari ruang atau DM. Peristiwa ini tidak memposting respons kembali ke Chat. Di Apps Script, Anda menentukan fungsi onRemoveFromSpace() untuk menangani peristiwa ini.
• MESSAGE: Peristiwa ini terjadi saat pengguna mengirim pesan ke aplikasi Chat, baik secara langsung di DM atau sebagai @sebutan di ruang. Di Apps Script, Anda menentukan fungsi onMessage() untuk merespons peristiwa ini.
• CARD_CLICKED: Peristiwa ini terjadi saat pengguna mengklik tombol dengan tindakan kustom yang ditetapkan padanya. Di Apps Script, Anda menentukan fungsi onCardClick() untuk merespons peristiwa ini.

Ganti konten file Code.gs dengan kode berikut yang menentukan pengendali untuk peristiwa ADDED_TO_SPACE dan REMOVE_FROM_SPACE. (Anda akan menambahkan pengendali untuk peristiwa MESSAGE dan CARD_CLICKED nanti di codelab ini.)

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/chat/api/guides/message-formats/events
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/chat/api/guides/message-formats/events
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. Memublikasikan & menguji aplikasi Chat

Mengupdate file manifes skrip

Sebelum dapat memublikasikan aplikasi ke Chat, Anda harus mengupdate manifes skrip.

1. Klik Setelan Project .
2. Pilih kotak centang Tampilkan file manifes "appsscript.json" dalam editor.
3. Klik Editor .
4. Klik file appsscript.json.
5. Tambahkan baris "chat": {} ke file manifes Anda.

File manifes Anda akan terlihat seperti contoh berikut.

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

Membuat project Google Cloud

Sebelum dapat menjalankan dan menguji aplikasi Chat, Anda harus membuat project Google Cloud, mengaktifkan dan mengonfigurasi Chat API, serta mempublikasikan aplikasi Chat ke organisasi Google Workspace Anda.

Catatan: Jika Anda menjalankan codelab ini dari kios di peristiwa yang dihosting Google, project Konsol Google Cloud sudah dibuat untuk Anda. Buka project tersebut dan langsung tuju item #3 dalam daftar di bawah ini.

1. Di Konsol Google Cloud, buka Menu > IAM & Admin > Create a Project.
   Create a project
   
2. Untuk Project Name, masukkan nama deskriptif.
3. Saat diminta, pilih Organization dan Billing Account.
4. Klik Create.
5. Saat pembuatan project selesai, sebuah notifikasi akan muncul di kanan atas halaman. Klik entri Create Project: <Project name> untuk membuka project.
6. Klik Menu > API & Services > Credentials.
7. Klik OAuth consent screen.
8. Untuk App name, masukkan Attendance Bot.
9. Jika diminta, masukkan email dukungan pengguna dan informasi kontak developer.
10. Klik Save and Continue.
11. Klik Settings and utilities > Project settings.
12. Salin Project number.
13. Kembali di editor App Script, klik Project Settings .
14. Pada Google Cloud Platform (GCP) Project, klik Change project.
15. Klik GCP project number lalu masukkan nomor project.
16. Klik Set project.

Memublikasikan aplikasi ke Chat

Untuk memublikasikan aplikasi Chat Anda ke Google Chat, lakukan hal berikut:

1. Di editor Apps Script, klik Deploy > Deployment baru.
2. Di sebelah Pilih jenis klik Aktifkan jenis deployment .
3. Pilih Add-on lalu klik Deploy.
4. Salin ID Deployment lalu klik Selesai.
5. Di konsol Google Cloud buka Menu > APIs & services > Library.
   Go to Library
   
6. Cari Google Chat API. Pilih API dari daftar hasil.
7. Di halaman Google Chat API, klik Enable.
8. Setelah mengaktifkan API, klik Configuration. Abaikan pesan apa pun yang meminta Anda membuat kredensial.
9. Di halaman Configuration, lakukan yang berikut:

• Untuk App name, masukkan Attendance Bot.
• Untuk Avatar URL, masukkan https://goo.gl/kv2ENA.
• Untuk Description, masukkan Apps Script codelab Chat app.
• Di bawah Functionality, pilih Receive one-to-one messages.
• Di bawah Connection settings, pilih Apps Script project lalu tempelkan ID Deployment skrip Anda ke dalam kotak teks.
• Di bawah Permissions, pilih Specific people and groups in your domain. Di kotak teks pada menu drop-down, masukkan alamat email Anda yang terkait dengan organisasi Google Workspace Anda.
• Klik Save.

Catatan: Jika Anda mencoba mengaktifkan Google Chat API dengan akun @gmail.com, Anda akan menerima pesan error:

The API "chat.googleapis.com" doesn't exist or you don't have permission to access it

Pastikan Anda login dengan akun Google Workspace dan/atau gunakan pengalih akun di kanan atas Konsol Cloud untuk beralih ke akun Google Workspace. Jika Anda membuat skrip dengan akun @gmail.com, Anda harus membagikannya dengan akun Google Workspace Anda.

Setelah Anda menyimpan perubahan, verifikasi bahwa status di halaman Google Chat API menampilkan App Status sebagai LIVE– available to users.

Menguji aplikasi Chat

Untuk menguji aplikasi Anda di Google Chat, lakukan hal berikut:

1. Buka Google Chat.
2. Kirim pesan langsung baru ke aplikasi Chat dengan mengeklik Mulai chat > Temukan aplikasi.
3. Di halaman Temukan aplikasi, cari Bot Kehadiran.
4. Di samping Bot Kehadiran, klik Tambahkan > Chat.

Saat rangkaian pesan langsung terbuka, Anda akan melihat pesan dari aplikasi Chat yang berterima kasih kepada Anda karena telah menambahkannya ke DM, seperti yang ditunjukkan pada gambar berikut.

Catatan: Kode untuk aplikasi Chat ini mencatat objek peristiwa yang diterima dari Google Chat ke dalam log. Anda dapat melihat struktur objek peristiwa dengan melihat log. Untuk membuka log, di editor Apps Script klik Lihat > Stackdriver Logging.

5. Mendefinisikan respons berformat kartu

Pada langkah sebelumnya, aplikasi Anda merespons peristiwa Google Chat dengan respons teks sederhana. Pada langkah ini, Anda akan mengupdate aplikasi agar merespons dengan kartu.

Respons kartu

Google Chat mendukung penggunaan kartu untuk merespons. Kartu adalah container visual yang dapat Anda gunakan untuk mengelompokkan set widget antarmuka pengguna. Kartu dapat menampilkan header, paragraf teks, set tombol, gambar, dan teks kunci/nilai. Aplikasi Anda dapat menentukan satu atau banyak kartu dalam respons JSON-nya ke Google Chat, yang kemudian menerjemahkan respons Anda ke dalam elemen UI yang sesuai.

Gambar berikut menampilkan respons kartu dengan tiga bagian, yang mencakup header, widget kunci/nilai, widget gambar, dan tombol teks.

Untuk merespons pesan pengguna dengan respons kartu, tambahkan kode berikut ke file Code.gs aplikasi Chat Anda.

Code.gs

var DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
var HEADER = {
  header: {
    title : 'Attendance Bot',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  var userMessage = event.message.text;

  var widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

Fungsi onMessage() yang ditambahkan pada langkah ini, membaca pesan asli pengguna dan membuat respons sebagai widget TextParagraph sederhana. Fungsi onMessage() selanjutnya akan memanggil createCardResponse(), yang menempatkan widget TextParagraph di dalam bagian dari satu kartu. Bot akan menampilkan objek JavaScript yang dibuat dengan respons kartu kembali ke Google Chat.

Menguji aplikasi Chat

Untuk menguji aplikasi ini, kembali ke pesan langsung Anda pada aplikasi di Google Chat lalu ketik pesan (pesan apa pun bisa).

Perhatikan bahwa pengendali peristiwa onMessage() akan mengurai objek peristiwa yang diteruskan oleh Google Chat untuk mengekstrak pesan asli pengguna. Anda juga bisa mendapatkan jenis informasi lain tentang peristiwa tersebut, termasuk nama pengguna yang memulai peristiwa, alamat email mereka, nama ruang tempat peristiwa berlangsung, dan banyak lagi.

Untuk mengetahui informasi selengkapnya tentang struktur objek peristiwa yang dikirim oleh Google Chat, baca Referensi format peristiwa.

6. Bereaksi terhadap klik tombol di kartu

Pada langkah sebelumnya, aplikasi Chat Anda merespons pesan dari pengguna—sebuah peristiwa MESSAGE—dengan kartu sederhana yang berisi widget TextParagragh. Pada langkah ini, Anda akan membuat respons yang menyertakan tombol, dan setiap tombol memiliki tindakan kustom yang ditentukan untuknya.

Kartu interaktif

Respons kartu dapat berisi salah satu dari dua jenis tombol: widget tombol teks, yang menampilkan tombol khusus teks; dan widget ImageButton, yang menampilkan tombol dengan ikon atau gambar sederhana tanpa teks. Widget TextButton dan ImageButton keduanya sama-sama mendukung salah satu dari dua perilaku onClick (sebagaimana didefinisikan dalam respons JSON yang dikirim kembali ke Google Chat): openLink atau action. Sesuai namanya, openLink akan membuka link tertentu di tab browser baru.

Objek action akan menentukan tindakan khusus untuk dilakukan tombol. Anda dapat menentukan beberapa nilai arbitrer dalam objek tindakan, termasuk actionMethodName unik dan satu set pasangan parameter kunci/nilai.

Menentukan objek action untuk tombol akan membuat sebuah kartu interaktif. Saat pengguna mengklik tombol di pesan, Google Chat akan memunculkan peristiwa CARD_CLICKED dan mengirimkan permintaan kembali ke aplikasi yang mengirim pesan asli. Aplikasi kemudian perlu menangani peristiwa yang muncul dari Google Chat dan menampilkan respons ke ruang.

Ganti fungsi onMessage() di Code.gs dengan kode berikut: Kode ini akan membuat 2 tombol, yakni tombol Setel liburan di Gmail dan tombol Blokir hari di Kalender di kartu yang dikirimkan ke Google Chat.

Code.gs

var REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  var reason = REASON.OTHER;
  var name = event.user.displayName;
  var userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  var widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

Untuk menangani peristiwa CARD_CLICKED, Anda harus menambahkan fungsi onCardClick() ke skrip aplikasi Chat Anda. Tambahkan kode berikut yang mendefinisikan fungsi onCardClick() sebagai Code.gs.

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/chat/api/guides/message-formats/events
 */
function onCardClick(event) {
  console.info(event);
  var message = '';
  var reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

Dalam menanggapi klik pengguna, aplikasi Chat akan melakukan salah satu dari dua hal berikut: menyetel penjawab saat libur pengguna di Gmail dengan pesan "sedang tidak di kantor"; atau menjadwalkan rapat sepanjang hari di Kalender pengguna. Untuk menyelesaikan tugas ini, aplikasi akan memanggil layanan lanjutan Gmail dan layanan Kalender.

Tambahkan kode berikut ke skrip Anda untuk mengintegrasikan aplikasi Chat dengan Gmail dan Kalender.

Code.gs

var ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  var currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Bot!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

Terakhir, Anda harus mengaktifkan layanan lanjutan Gmail di project. Untuk mengaktifkan Gmail API, lakukan hal berikut:

1. Di editor Apps Script, di samping Layanan, klik Tambahkan layanan .
2. Pilih Gmail API.
3. Klik Dasbor Google Cloud Platform API di bawah yang akan membuka Konsol Google Cloud.
4. Klik Aktifkan API dan Layanan.
5. Cari Gmail API lalu klik Gmail API tersebut.
6. Di halaman Gmail API, klik Aktifkan.

Menguji aplikasi Chat

Untuk menguji versi aplikasi Chat Anda ini, buka DM yang Anda mulai pada langkah sebelumnya di Google Chat lalu ketik Saya akan berlibur. Aplikasi akan merespons dengan kartu yang mirip dengan gambar di bawah.

Catatan: Jika Anda diminta untuk memberikan akses ke aplikasi, Anda mungkin harus mengetik pesan untuk kedua kalinya.

7. Selamat!

Aplikasi Chat Anda kini dapat menanggapi pesan pengguna, menyetel penjawab saat libur di Gmail, dan memasukkan acara sepanjang hari di Kalender mereka.

Yang telah kita bahas

• Membangun dan memublikasikan aplikasi Google Chat dengan Apps Script
• Merespons pesan pengguna dengan respons sederhana
• Berinteraksi dengan layanan Google Workspace lainnya atas nama pengguna melalui Aplikasi Chat

Pelajari lebih lanjut

• Situs dokumentasi Google Chat
• Panduan memulai aplikasi Chat Apps Script
• Membuat aplikasi Chat
• Memublikasikan aplikasi Chat
• Membuat kartu interaktif
• Referensi kartu
• Referensi objek peristiwa
• Referensi layanan lanjutan Gmail
• Referensi layanan Kalender