Kirim pesan kartu

Selain pesan teks, aplikasi Chat dapat mengirim pesan kartu dalam ruang dan kepada pengguna. Kartu mendukung tata letak yang ditentukan, elemen UI interaktif seperti tombol, dan multimedia seperti gambar.

Gunakan pesan kartu untuk:

• Mempresentasikan informasi mendetail
• Mengumpulkan informasi dari pengguna
• Pandu pengguna untuk melakukan langkah berikutnya

Panduan ini menjelaskan cara mengirim pesan kartu secara sinkron (respons realtime ke peristiwa Chat, seperti menerima pesan dari pengguna atau ditambahkan ke ruang) dan secara asinkron (mengirim pesan dari aplikasi ke ruang atau pengguna tanpa perintah menggunakan Chat REST API).

Prasyarat

Untuk mengirim pesan kartu dalam panduan ini, Anda memerlukan hal berikut:

Node.js

• Akun Google Workspace dengan akses ke Google Chat.
• Aplikasi Chat. Untuk membuat aplikasi Chat, ikuti panduan memulai ini.

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

Python

• Akun Google Workspace dengan akses ke Google Chat.
• Aplikasi Chat. Untuk membuat aplikasi Chat, ikuti panduan memulai ini.

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

Apps Script

• Akun Google Workspace dengan akses ke Google Chat.
• Aplikasi Chat. Untuk membuat aplikasi Chat, ikuti panduan memulai ini.

Anatomi pesan kartu

Setiap kartu, baik itu dialog atau pesan, adalah objek JSON pada resource spaces.messages di Chat API.

Objek JSON kartu terdiri dari hal-hal berikut:

1. Array bernama cardsV2[] yang berisi satu atau beberapa objek CardWithId.
2. cardId, digunakan untuk mengidentifikasi kartu dan diberi cakupan dalam pesan tertentu. (Kartu dalam pesan yang berbeda dapat memiliki ID yang sama.)

3. Objek card, yang terdiri dari berikut:

   • Objek header yang menentukan berbagai hal seperti judul, subtitel, dan gambar bergaya avatar.
   • Satu atau beberapa objek section yang masing-masing berisi setidaknya satu widget.

   • Satu atau beberapa objek widget. Setiap widget adalah objek gabungan yang dapat mewakili teks, gambar, tombol, dan jenis objek lainnya.

     Widget berikut didukung dalam pesan dan dialog kartu:

     • TextParagraph–Menampilkan paragraf teks dengan format HTML sederhana opsional.
     • Image–Menampilkan gambar .PNG atau .JPG yang dapat diklik atau statis yang dihosting di URL HTTPS.
     • DecoratedText–Menampilkan teks dengan fitur tata letak dan fungsi opsional, seperti ikon dan tombol.
     • ButtonList–Menampilkan serangkaian tombol.

     Widget berikut didukung dalam dialog (dukungan untuk pesan kartu akan segera hadir):

     • TextInput–Kolom tempat pengguna dapat memasukkan teks.

     • SelectionInput–Menyediakan kumpulan item yang dapat dipilih, seperti daftar kotak centang, tombol pilihan, tombol akses, atau menu dropdown.

     • Divider–Menampilkan garis horizontal yang membentang lebar kartu di antara widget bertumpuk, yang bertindak sebagai pemisah visual.

     • Grid–Meletakkan sekumpulan item dalam petak sederhana.

     Dukungan untuk widget berikut akan segera hadir:

     • DateTimePicker–Memungkinkan pengguna menentukan tanggal, waktu, atau keduanya.

Misalnya, amati objek header, section, dan widget dalam pesan kartu berikut:

Kode berikut mewakili JSON dari pesan kartu:

JSON

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
          "title": "Sasha",
          "subtitle": "Software Engineer",
          "imageUrl":
          "https://developers.google.com/chat/images/quickstart-app-avatar.png",
          "imageType": "CIRCLE",
          "imageAltText": "Avatar for Sasha",
        },
        "sections": [
          {
            "header": "Contact Info",
            "collapsible": true,
            "uncollapsibleWidgetsCount": 1,
            "widgets": [
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "EMAIL",
                  },
                  "text": "[e-mail]",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "[phone]",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Mengirim pesan kartu sinkron

Dalam contoh ini, pengguna mengirim pesan ke aplikasi Chat di Google Chat dan aplikasi merespons dengan mengirimkan pesan kartu sinkron sederhana yang menampilkan nama dan gambar avatar pengirim:

Dalam contoh kode berikut, aplikasi Node.js dan Python dihosting di Google Cloud Functions. Contoh Apps Script dihosting di Google Apps Script.

Untuk mendapatkan petunjuk lengkap yang menjelaskan cara mem-build dan men-deploy aplikasi Chat, lihat Mem-build aplikasi Chat.

Node.js

node/avatar-bot/index.js

Lihat di GitHub

/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-bot/main.py

Lihat di GitHub

from typing import Any, Mapping

import flask
import functions_framework

# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request):
    if req.method == "GET":
        return "Hello! This function must be called from Google Chat."

    request_json = req.get_json(silent=True)

    display_name = request_json["message"]["sender"]["displayName"]
    avatar = request_json["message"]["sender"]["avatarUrl"]

    response = create_message(name=display_name, image_url=avatar)

    return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
    avatar_image_widget = {"image": {"imageUrl": image_url}}
    avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
    avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

    header = {"title": f"Hello {name}!"}

    cards = {
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": header,
                    "sections": [avatar_section],
                },
            }
        ]
    }

    return cards

Apps Script

apps-script/avatar-bot/hello-chat.gs

Lihat di GitHub

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Mengirim pesan kartu asinkron dengan Chat API

Contoh ini secara asinkron membuat pesan dengan Chat API dan mengirimkannya ke ruang tempat aplikasi Chat ditambahkan, seperti yang ditunjukkan di bawah ini:

Gambar 1: Pesan kartu yang dibuat dengan Chat REST API.

Python

1. Dalam direktori kerja, buat file bernama chat_create_card_message.py.

2. Sertakan kode berikut di chat_create_card_message.py:

   from httplib2 import Http
   from oauth2client.service_account import ServiceAccountCredentials
   from apiclient.discovery import build
   
   # Specify required scopes.
   SCOPES = ['https://www.googleapis.com/auth/chat.bot']
   
   # Specify service account details.
   CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
       'service_account.json', SCOPES)
   
   # Build the URI and authenticate with the service account.
   chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
   
   # Create a Chat message.
   result = chat.spaces().messages().create(
   
       # The space to create the message in.
       #
       # Replace SPACE with a space name.
       # Obtain the space name from the spaces resource of Chat API,
       # or from a space's URL.
       parent='spaces/SPACE',
   
       # The message to create.
       body=
       {
         'cardsV2': [{
           'cardId': 'createCardMessage',
           'card': {
             'header': {
               'title': 'A Card Message!',
               'subtitle': 'Created with Chat REST API',
               'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
               'imageType': 'CIRCLE'
             },
             'sections': [
               {
                 'widgets': [
                   {
                     'buttonList': {
                       'buttons': [
                         {
                           'text': 'Read the docs!',
                           'onClick': {
                             'openLink': {
                               'url': 'https://developers.google.com/chat'
                             }
                           }
                         }
                       ]
                     }
                   }
                 ]
               }
             ]
           }
         }]
       }
   
   ).execute()
   
   print(result)
   

3. Di dalam kode, ganti SPACE dengan nama ruang, yang dapat diperoleh dari metode spaces.list() di Chat API, atau dari URL ruang.

4. Dalam direktori kerja Anda, buat dan jalankan contoh:

   python3 chat_create_card_message.py
   

Untuk mempelajari lebih lanjut cara bekerja dengan pesan di Chat REST API, lihat Membuat, membaca, memperbarui, menghapus pesan.

Membuka dialog

Dialog adalah antarmuka berbasis kartu dengan jendela yang terbuka agar aplikasi Chat dapat berinteraksi dengan pengguna. Untuk membantu pengguna menyelesaikan proses multi-langkah, aplikasi dapat membuka dialog berurutan. Aplikasi dapat membuka dialog sebagai respons terhadap klik tombol pada pesan kartu atau sebagai respons terhadap perintah garis miring.

Dialog berguna untuk berbagai jenis interaksi pengguna, termasuk:

• Mengumpulkan informasi dari pengguna
• Mengautentikasi pengguna dengan Layanan web
• Mengonfigurasi setelan aplikasi Chat

Dalam contoh ini, aplikasi Chat akan membuka dialog guna membantu pengguna membuat kontak baru untuk buku alamatnya:

Untuk menerapkan dialog, lihat Membuka dialog.

Pemformatan kartu

Pemformatan teks kartu

Di dalam kartu, sebagian besar kolom teks mendukung pemformatan teks dasar melalui subset kecil tag HTML. Tag yang didukung dan tujuannya ditampilkan dalam tabel di bawah:

Tebal	<b>		Miring	<i>
Garis bawah	<>		Coret	<teguran>
Warna Font	<font color="">		Hyperlink	<a href="">
Jeda Baris	<br>

Perhatikan bahwa isi teks pesan dasar diuraikan menggunakan sintaksis markup lain yang dioptimalkan untuk pengguna manusia. Untuk mengetahui detailnya, lihat Mengirim SMS.

Ikon bawaan

Widget DecoratedText dan ButtonList mendukung elemen icon yang digunakan untuk menentukan salah satu ikon bawaan yang tersedia di Google Chat:

{
  .
  .
  .
      "knownIcon": "TRAIN",
  .
  .
  .
}

Tabel berikut mencantumkan ikon bawaan yang tersedia untuk pesan kartu:

	pesawat terbang		TANDAI BUKU
	Amerika Serikat		AR
	JAM		KONFIRMASI_NUMBER_ICON
	DESCRIPTION		DOLAR
	EMAIL		KAMPANYE_PERISTIWA
	PENARIK_DAPAT		PENJUALAN_PELANGGAN
	HOTEL		HOTEL_ROOM_TYPE
	UNDANG		PIN_MAP
	LANGGANAN		BEBERAPA_ORANG
	ORANG		TELEPON
	ICON_REST		KARTU_BELANJA
	STAR		TOKO
	TIKET		PELATIHAN
	KAMERA_VIDEO		VIDEO_PLAY

Ikon khusus

Widget DecoratedText dan ButtonList memungkinkan Anda menggunakan ikon bawaan yang tercantum di atas, atau menentukan ikon kustom Anda sendiri. Untuk menentukan ikon kustom, gunakan elemen iconUrl seperti yang ditunjukkan di sini:

{ . . . "iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png" . . . }

Batas dan pertimbangan

Saat bersiap untuk mengirim pesan kartu, perhatikan batasan dan pertimbangan berikut.

• Widget berikut tidak didukung oleh pesan kartu, tetapi dukungan akan segera hadir:

  • TextInput, kolom tempat pengguna dapat memasukkan teks.
  • SelectionInput, yang menyediakan kumpulan item yang dapat dipilih, seperti daftar kotak centang, tombol pilihan, tombol akses, atau menu dropdown.
  • DateTimePicker, yang memungkinkan pengguna menentukan tanggal, waktu, atau keduanya.
  • Grid, yang menata kumpulan item dalam petak sederhana.