Mengirim pesan pribadi ke pengguna Google Chat

Halaman ini menjelaskan cara membuat dan mengirim pesan pribadi sebagai aplikasi Google Chat.

Pesan pribadi adalah pesan aplikasi Chat yang hanya terlihat oleh pengguna Chat tertentu. Anda dapat menggunakan pesan pribadi di ruang dengan beberapa orang agar mereka dapat berinteraksi secara pribadi dengan aplikasi Chat. Misalnya, aplikasi Chat Anda dapat mengirim pesan secara pribadi untuk melakukan salah satu hal berikut:

  • Respons perintah garis miring. Misalnya, jika pengguna memanggil perintah garis miring /about pada aplikasi Chat dalam ruang, aplikasi Chat Anda dapat membalas dengan pesan pribadi yang menjelaskan apa yang dilakukan aplikasi Chat Anda dan cara menggunakannya.
  • Memberi tahu atau mengirim informasi yang hanya relevan bagi satu pengguna. Misalnya, beri tahu pengguna bahwa mereka telah diberi tugas, atau ingatkan mereka untuk menyelesaikan tugas tersebut.
  • Kirim pesan error. Misalnya, jika pengguna menghilangkan teks argumen yang diperlukan untuk perintah garis miring, aplikasi Chat dapat mengirim pesan pribadi untuk menjelaskan error dan membantu pengguna memformat perintah tersebut.

Saat aplikasi Chat mengirim pesan pribadi, pesan tersebut akan menampilkan label yang memberi tahu pengguna bahwa pesan tersebut hanya dapat dilihat oleh mereka:

Pesan pribadi untuk aplikasi Chat Cymbal Labs. Pesan ini menyatakan bahwa aplikasi Chat dibuat oleh Cymbal Labs dan membagikan link ke dokumentasi serta link untuk menghubungi tim dukungan.
Gambar 1: Saat aplikasi Chat mengirim pesan pribadi, pengguna akan melihat pesan dengan label yang bertuliskan Only visible to you.

Prasyarat

Node.js

Catatan: Contoh kode Node.js dalam panduan ini ditulis untuk dijalankan sebagai Google Cloud Function.

Python

Catatan: Contoh kode Python dalam panduan ini ditulis untuk dijalankan sebagai Google Cloud Function, menggunakan Python 3.10.

Apps Script

Kirim pesan pribadi

Untuk mengirim pesan secara pribadi sebagai aplikasi Chat, Anda harus menentukan kolom privateMessageViewer dalam pesan saat membuatnya. Anda dapat membuat pesan pribadi seperti saat membuat pesan apa pun: dengan merespons interaksi pengguna, atau memanggil metode create() Google Chat API secara asinkron pada resource Message. Untuk mengetahui langkah-langkah dalam mengirim pesan teks atau kartu, baca artikel Mengirim pesan.

Contoh berikut menunjukkan JSON untuk pesan teks pribadi yang bertuliskan Hello private world!:

{
    "text": "Hello private world!",
    "privateMessageViewer": "USER"
}

Dalam contoh ini, USER merepresentasikan pengguna Chat yang dapat melihat pesan, yang diformat sebagai resource User. Jika merespons interaksi pengguna, Anda dapat menentukan objek User dari peristiwa interaksi. Sebagai contoh, lihat bagian berikut Merespons perintah garis miring secara pribadi.

Jika tidak, untuk menentukan pelihat pesan pribadi, Anda dapat menggunakan kolom name dari resource User:

{
    "text": "Hello private world!",
    "privateMessageViewer": {
      "name": "users/USER_ID"
    }
}

Dalam contoh ini, Anda menggunakan kolom name untuk menentukan nama resource User penonton di Google Chat. Ganti USER_ID dengan ID unik untuk pengguna, seperti 12345678987654321 atau hao@cymbalgroup.com.

Untuk mengetahui informasi selengkapnya tentang cara menentukan pengguna, lihat Mengidentifikasi dan menentukan pengguna Google Chat.

Merespons secara pribadi perintah garis miring

Kode berikut menunjukkan contoh aplikasi Chat yang merespons perintah garis miring dengan pesan pribadi.

Aplikasi Chat memproses peristiwa interaksi MESSAGE dan membalas perintah garis miring /help dengan pesan teks pribadi yang menjelaskan cara menggunakannya:

Node.js 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case '1':  // /help
        return res.json({
          privateMessageViewer: event.user,
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

Apps Script 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1: // Responds to /help
        return {
          "privateMessageViewer": event.user,
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python 

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == '1':  # /help
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'),
      'text': 'Try a slash command.',
  }

Batasan

Untuk mengirim pesan pribadi, pesan tidak boleh berisi atau menggunakan hal berikut:

  • Lampiran.
  • Tindakan aksesori.
  • Pesan pribadi sebagian. Misalnya, aplikasi Chat tidak dapat mengirim pesan yang berisi teks dan kartu yang teksnya hanya dapat dilihat oleh satu pengguna, tetapi kartu dapat dilihat oleh semua orang dalam ruang.
  • Autentikasi pengguna. Hanya aplikasi Chat yang dapat mengirim pesan pribadi, sehingga aplikasi Chat Anda tidak dapat melakukan autentikasi sebagai pengguna untuk mengirim pesan secara pribadi.

Memperbarui atau menghapus pesan pribadi

Untuk memperbarui atau menghapus pesan Google Chat, Anda harus memanggil Chat API. Anda tidak dapat mengubah penampil pesan pribadi atau memublikasikan pesan. Oleh karena itu, saat memperbarui pesan pribadi, Anda harus menghilangkan kolom privateMessageViewer dalam panggilan API (kolomnya hanya merupakan output).

Untuk memperbarui pesan pribadi, lihat Memperbarui pesan. Untuk menghapus pesan pribadi, lihat Menghapus pesan.